@popoverai/dotrequirements 0.11.0

package/dist/schema/schemas.d.ts

@@ -0,0 +1,312 @@
+/**
+ * Zod schemas for Markdown requirements format.
+ * TypeScript types are inferred from these schemas using z.infer<>.
+ */
+import { z } from 'zod';
+/**
+ * Requirement prefix format: uppercase letters and hyphens, 1-30 chars.
+ * First char must be a letter.
+ * Examples: "LOGIN", "AUTH", "SYNC-CLI-CREATE", "ADMIN-PROJECT"
+ */
+export declare const REQUIREMENT_PREFIX_PATTERN: RegExp;
+/**
+ * Requirement key format: PREFIX-number.
+ * Examples: "LOGIN-1", "AUTH-42", "USAGE-0"
+ */
+export declare const REQUIREMENT_KEY_PATTERN: RegExp;
+/**
+ * Zod schema for requirement prefix.
+ * Accepts any case input but validates the uppercase form.
+ */
+export declare const RequirementPrefixSchema: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+export type RequirementPrefix = z.infer<typeof RequirementPrefixSchema>;
+/**
+ * Zod schema for requirement key (PREFIX-number).
+ * Normalizes to uppercase and strips leading zeros from numbers.
+ */
+export declare const RequirementKeySchema: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+export type RequirementKey = z.infer<typeof RequirementKeySchema>;
+/**
+ * Normalize a prefix to uppercase.
+ * Does not validate - use validatePrefix for validation.
+ */
+export declare function normalizePrefix(prefix: string): string;
+/**
+ * Validate a prefix string.
+ * Returns the normalized (uppercase) prefix or throws ValidationError.
+ */
+export declare function validatePrefix(prefix: string): string;
+/**
+ * Validate a requirement key string.
+ * Returns the normalized (uppercase) key or throws ValidationError.
+ */
+export declare function validateKey(key: string): string;
+/**
+ * Parse a requirement key into prefix and number parts.
+ * Returns null if the key doesn't match the expected format.
+ */
+export declare function parseRequirementKey(key: string): {
+    prefix: string;
+    number: number;
+} | null;
+/**
+ * Build a requirement key from prefix and number.
+ */
+export declare function buildRequirementKey(prefix: string, number: number): string;
+/**
+ * Metadata block at the top of every requirements file
+ */
+export declare const MetadataSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    projectSlug: z.ZodOptional<z.ZodString>;
+    pulledAt: z.ZodOptional<z.ZodString>;
+    version: z.ZodNumber;
+    document: z.ZodOptional<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        defaultPrefix: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        title: string;
+        id?: string | undefined;
+        defaultPrefix?: string | undefined;
+    }, {
+        title: string;
+        id?: string | undefined;
+        defaultPrefix?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    version: number;
+    projectId: string;
+    projectSlug?: string | undefined;
+    pulledAt?: string | undefined;
+    document?: {
+        title: string;
+        id?: string | undefined;
+        defaultPrefix?: string | undefined;
+    } | undefined;
+}, {
+    version: number;
+    projectId: string;
+    projectSlug?: string | undefined;
+    pulledAt?: string | undefined;
+    document?: {
+        title: string;
+        id?: string | undefined;
+        defaultPrefix?: string | undefined;
+    } | undefined;
+}>;
+export type Metadata = z.infer<typeof MetadataSchema>;
+/**
+ * Convex document ID format: 32 lowercase alphanumeric characters starting with 'j'
+ */
+export declare const CONVEX_ID_PATTERN: RegExp;
+/**
+ * Result of validating a file for push readiness.
+ */
+export type PushValidationResult = {
+    valid: true;
+    action: 'create' | 'update';
+    warning?: string;
+} | {
+    valid: false;
+    reason: string;
+};
+/**
+ * Validate metadata for push readiness.
+ * Returns whether the file can be pushed and what action will be taken.
+ *
+ * SYNC-CLI-CREATE-1: Files without document.id create new documents
+ * SYNC-CLI-EDIT-1: Files with valid document.id update existing documents
+ */
+export declare function validateForPush(metadata: Metadata): PushValidationResult;
+/**
+ * Individual requirement node in the tree.
+ * Each node has an ID, label, content, and optional children.
+ */
+export declare const RequirementNodeSchema: z.ZodType<RequirementNode>;
+export type RequirementNode = {
+    id: string;
+    label: string;
+    content: string;
+    children: RequirementNode[];
+    metadata?: {
+        convexId?: string;
+        rootId?: string;
+        position?: string;
+        updatedAt?: number;
+        externalLinks?: {
+            jira?: string;
+            notion?: string;
+        };
+        prefix?: string;
+        index?: number;
+        documentId?: string;
+    };
+};
+/**
+ * Complete requirements file structure.
+ * Top-level keys are either "_meta" or requirement IDs.
+ */
+export declare const RequirementsFileSchema: z.ZodObject<{
+    _meta: z.ZodObject<{
+        projectId: z.ZodString;
+        projectSlug: z.ZodOptional<z.ZodString>;
+        pulledAt: z.ZodOptional<z.ZodString>;
+        version: z.ZodNumber;
+        document: z.ZodOptional<z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
+            title: z.ZodString;
+            defaultPrefix: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            title: string;
+            id?: string | undefined;
+            defaultPrefix?: string | undefined;
+        }, {
+            title: string;
+            id?: string | undefined;
+            defaultPrefix?: string | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        version: number;
+        projectId: string;
+        projectSlug?: string | undefined;
+        pulledAt?: string | undefined;
+        document?: {
+            title: string;
+            id?: string | undefined;
+            defaultPrefix?: string | undefined;
+        } | undefined;
+    }, {
+        version: number;
+        projectId: string;
+        projectSlug?: string | undefined;
+        pulledAt?: string | undefined;
+        document?: {
+            title: string;
+            id?: string | undefined;
+            defaultPrefix?: string | undefined;
+        } | undefined;
+    }>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    _meta: z.ZodObject<{
+        projectId: z.ZodString;
+        projectSlug: z.ZodOptional<z.ZodString>;
+        pulledAt: z.ZodOptional<z.ZodString>;
+        version: z.ZodNumber;
+        document: z.ZodOptional<z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
+            title: z.ZodString;
+            defaultPrefix: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            title: string;
+            id?: string | undefined;
+            defaultPrefix?: string | undefined;
+        }, {
+            title: string;
+            id?: string | undefined;
+            defaultPrefix?: string | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        version: number;
+        projectId: string;
+        projectSlug?: string | undefined;
+        pulledAt?: string | undefined;
+        document?: {
+            title: string;
+            id?: string | undefined;
+            defaultPrefix?: string | undefined;
+        } | undefined;
+    }, {
+        version: number;
+        projectId: string;
+        projectSlug?: string | undefined;
+        pulledAt?: string | undefined;
+        document?: {
+            title: string;
+            id?: string | undefined;
+            defaultPrefix?: string | undefined;
+        } | undefined;
+    }>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    _meta: z.ZodObject<{
+        projectId: z.ZodString;
+        projectSlug: z.ZodOptional<z.ZodString>;
+        pulledAt: z.ZodOptional<z.ZodString>;
+        version: z.ZodNumber;
+        document: z.ZodOptional<z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
+            title: z.ZodString;
+            defaultPrefix: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            title: string;
+            id?: string | undefined;
+            defaultPrefix?: string | undefined;
+        }, {
+            title: string;
+            id?: string | undefined;
+            defaultPrefix?: string | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        version: number;
+        projectId: string;
+        projectSlug?: string | undefined;
+        pulledAt?: string | undefined;
+        document?: {
+            title: string;
+            id?: string | undefined;
+            defaultPrefix?: string | undefined;
+        } | undefined;
+    }, {
+        version: number;
+        projectId: string;
+        projectSlug?: string | undefined;
+        pulledAt?: string | undefined;
+        document?: {
+            title: string;
+            id?: string | undefined;
+            defaultPrefix?: string | undefined;
+        } | undefined;
+    }>;
+}, z.ZodTypeAny, "passthrough">>;
+export type RequirementsFile = z.infer<typeof RequirementsFileSchema> & {
+    [key: string]: any;
+};
+/**
+ * Parsed criterion from Markdown (position. Label: content format)
+ * Example: "0. Given: user has valid credentials"
+ */
+export declare const ParsedCriterionSchema: z.ZodObject<{
+    position: z.ZodString;
+    label: z.ZodString;
+    content: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    label: string;
+    content: string;
+    position: string;
+}, {
+    label: string;
+    content: string;
+    position: string;
+}>;
+export type ParsedCriterion = z.infer<typeof ParsedCriterionSchema>;
+/**
+ * Validation error with context
+ */
+export declare class ValidationError extends Error {
+    path?: string | undefined;
+    cause?: unknown | undefined;
+    constructor(message: string, path?: string | undefined, cause?: unknown | undefined);
+}
+/**
+ * Validate metadata block
+ */
+export declare function validateMetadata(data: unknown): Metadata;
+/**
+ * Validate requirement node structure
+ */
+export declare function validateRequirementNode(data: unknown, path: string): RequirementNode;
+/**
+ * Validate complete requirements file
+ */
+export declare function validateRequirementsFile(data: unknown): RequirementsFile;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/schema/schemas.js

@@ -0,0 +1,258 @@
+/**
+ * Zod schemas for Markdown requirements format.
+ * TypeScript types are inferred from these schemas using z.infer<>.
+ */
+import { z } from 'zod';
+import { fromZodError } from 'zod-validation-error';
+// =============================================================================
+// Prefix and Key Validation
+// =============================================================================
+/**
+ * Requirement prefix format: uppercase letters and hyphens, 1-30 chars.
+ * First char must be a letter.
+ * Examples: "LOGIN", "AUTH", "SYNC-CLI-CREATE", "ADMIN-PROJECT"
+ */
+export const REQUIREMENT_PREFIX_PATTERN = /^[A-Z][A-Z-]{0,29}$/;
+/**
+ * Requirement key format: PREFIX-number.
+ * Examples: "LOGIN-1", "AUTH-42", "USAGE-0"
+ */
+export const REQUIREMENT_KEY_PATTERN = /^[A-Z][A-Z-]*-[0-9]+$/;
+/**
+ * Zod schema for requirement prefix.
+ * Accepts any case input but validates the uppercase form.
+ */
+export const RequirementPrefixSchema = z
+    .string()
+    .min(1, 'Prefix must be at least 1 character')
+    .max(30, 'Prefix must be at most 30 characters')
+    .transform((val) => val.toUpperCase())
+    .refine((val) => REQUIREMENT_PREFIX_PATTERN.test(val), 'Prefix must start with a letter and contain only uppercase letters and hyphens');
+/**
+ * Zod schema for requirement key (PREFIX-number).
+ * Normalizes to uppercase and strips leading zeros from numbers.
+ */
+export const RequirementKeySchema = z
+    .string()
+    .refine((val) => REQUIREMENT_KEY_PATTERN.test(val.toUpperCase()), 'Key must be in format PREFIX-number (e.g., LOGIN-1, AUTH-42)')
+    .transform((val) => {
+    const upper = val.toUpperCase();
+    // Normalize leading zeros: LOGIN-01 -> LOGIN-1, LOGIN-007 -> LOGIN-7
+    return upper.replace(/-0+(\d+)$/, '-$1');
+});
+/**
+ * Normalize a prefix to uppercase.
+ * Does not validate - use validatePrefix for validation.
+ */
+export function normalizePrefix(prefix) {
+    return prefix.toUpperCase();
+}
+/**
+ * Validate a prefix string.
+ * Returns the normalized (uppercase) prefix or throws ValidationError.
+ */
+export function validatePrefix(prefix) {
+    const result = RequirementPrefixSchema.safeParse(prefix);
+    if (!result.success) {
+        const validationError = fromZodError(result.error);
+        throw new ValidationError(`Invalid prefix "${prefix}": ${validationError.message}`, 'prefix', result.error);
+    }
+    return result.data;
+}
+/**
+ * Validate a requirement key string.
+ * Returns the normalized (uppercase) key or throws ValidationError.
+ */
+export function validateKey(key) {
+    const result = RequirementKeySchema.safeParse(key);
+    if (!result.success) {
+        const validationError = fromZodError(result.error);
+        throw new ValidationError(`Invalid key "${key}": ${validationError.message}`, 'key', result.error);
+    }
+    return result.data;
+}
+/**
+ * Parse a requirement key into prefix and number parts.
+ * Returns null if the key doesn't match the expected format.
+ */
+export function parseRequirementKey(key) {
+    const normalized = key.toUpperCase();
+    // Find the last hyphen followed by digits - that's the number part
+    const match = normalized.match(/^(.+)-([0-9]+)$/);
+    if (!match)
+        return null;
+    const [, prefix, numStr] = match;
+    // Validate the prefix part
+    if (!REQUIREMENT_PREFIX_PATTERN.test(prefix))
+        return null;
+    return { prefix, number: parseInt(numStr, 10) };
+}
+/**
+ * Build a requirement key from prefix and number.
+ */
+export function buildRequirementKey(prefix, number) {
+    const normalizedPrefix = prefix.toUpperCase();
+    if (!REQUIREMENT_PREFIX_PATTERN.test(normalizedPrefix)) {
+        throw new ValidationError(`Invalid prefix "${prefix}": must match pattern ${REQUIREMENT_PREFIX_PATTERN}`, 'prefix');
+    }
+    if (number < 0 || !Number.isInteger(number)) {
+        throw new ValidationError(`Invalid number "${number}": must be a non-negative integer`, 'number');
+    }
+    return `${normalizedPrefix}-${number}`;
+}
+// =============================================================================
+// Metadata Schema
+// =============================================================================
+/**
+ * Metadata block at the top of every requirements file
+ */
+export const MetadataSchema = z.object({
+    projectId: z.string(),
+    projectSlug: z.string().optional(), // User-friendly slug (e.g., "quick-fox-123")
+    pulledAt: z.string().optional(), // ISO 8601 timestamp - required for CLI files, optional for IDE
+    version: z.number(),
+    // Optional document association (one file = one document)
+    document: z.object({
+        id: z.string().optional(), // Optional - filled by push when creating new document
+        title: z.string(),
+        // DOC-HEADER-11: Default prefix for new requirement keys in this document
+        defaultPrefix: z.string().optional(),
+    }).optional(),
+});
+// =============================================================================
+// Push Readiness Validation
+// =============================================================================
+/**
+ * Convex document ID format: 32 lowercase alphanumeric characters starting with 'j'
+ */
+export const CONVEX_ID_PATTERN = /^j[a-z0-9]{31}$/;
+/**
+ * Validate metadata for push readiness.
+ * Returns whether the file can be pushed and what action will be taken.
+ *
+ * SYNC-CLI-CREATE-1: Files without document.id create new documents
+ * SYNC-CLI-EDIT-1: Files with valid document.id update existing documents
+ */
+export function validateForPush(metadata) {
+    // Must have document section
+    if (!metadata.document) {
+        return {
+            valid: false,
+            reason: 'Missing document section. Add a document section with a title to push this file.'
+        };
+    }
+    // Must have title
+    if (!metadata.document.title || metadata.document.title.trim() === '') {
+        return {
+            valid: false,
+            reason: 'Document section missing required title.'
+        };
+    }
+    // Check document.id
+    if (!metadata.document.id) {
+        // No ID = create new document
+        return { valid: true, action: 'create' };
+    }
+    // Has ID - check if it's a valid Convex ID
+    if (CONVEX_ID_PATTERN.test(metadata.document.id)) {
+        // Valid Convex ID = update existing document
+        return { valid: true, action: 'update' };
+    }
+    // Invalid ID format - will create new document and overwrite
+    return {
+        valid: true,
+        action: 'create',
+        warning: `Invalid document ID '${metadata.document.id}' will be replaced with a new ID.`
+    };
+}
+/**
+ * Individual requirement node in the tree.
+ * Each node has an ID, label, content, and optional children.
+ */
+export const RequirementNodeSchema = z.lazy(() => z.object({
+    id: z.string(), // e.g., "REQ123" or "REQ123.0.1"
+    label: z.string(), // e.g., "given", "when", "then", "requirement"
+    content: z.string(), // The actual requirement text
+    children: z.array(RequirementNodeSchema).default([]),
+    // Optional metadata preserved from Convex
+    metadata: z.object({
+        convexId: z.string().optional(), // Convex _id
+        rootId: z.string().optional(), // Convex rootId
+        position: z.string().optional(), // Convex position path
+        updatedAt: z.number().optional(),
+        externalLinks: z.object({
+            jira: z.string().optional(),
+            notion: z.string().optional(),
+        }).optional(),
+        // New schema fields for bidirectional sync
+        prefix: z.string().optional(), // e.g., "REQ"
+        index: z.number().optional(), // e.g., 123
+        documentId: z.string().optional(), // Convex document ID
+    }).optional(),
+}));
+/**
+ * Complete requirements file structure.
+ * Top-level keys are either "_meta" or requirement IDs.
+ */
+export const RequirementsFileSchema = z.object({
+    _meta: MetadataSchema,
+    // All other keys are requirement roots
+    // We'll validate the structure separately since Zod doesn't handle
+    // arbitrary keys with specific structure well
+}).passthrough(); // Allow additional keys
+/**
+ * Parsed criterion from Markdown (position. Label: content format)
+ * Example: "0. Given: user has valid credentials"
+ */
+export const ParsedCriterionSchema = z.object({
+    position: z.string(), // e.g., "0", "1.0", "2.3.1"
+    label: z.string(), // e.g., "given", "when", "then"
+    content: z.string(), // The criterion text
+});
+/**
+ * Validation error with context
+ */
+export class ValidationError extends Error {
+    path;
+    cause;
+    constructor(message, path, cause) {
+        super(message);
+        this.path = path;
+        this.cause = cause;
+        this.name = 'ValidationError';
+    }
+}
+/**
+ * Validate metadata block
+ */
+export function validateMetadata(data) {
+    const result = MetadataSchema.safeParse(data);
+    if (!result.success) {
+        const validationError = fromZodError(result.error);
+        throw new ValidationError(`Invalid metadata block:\n${validationError.message}`, '_meta', result.error);
+    }
+    return result.data;
+}
+/**
+ * Validate requirement node structure
+ */
+export function validateRequirementNode(data, path) {
+    const result = RequirementNodeSchema.safeParse(data);
+    if (!result.success) {
+        const validationError = fromZodError(result.error);
+        throw new ValidationError(`Invalid requirement node structure at ${path}:\n${validationError.message}`, path, result.error);
+    }
+    return result.data;
+}
+/**
+ * Validate complete requirements file
+ */
+export function validateRequirementsFile(data) {
+    const result = RequirementsFileSchema.safeParse(data);
+    if (!result.success) {
+        const validationError = fromZodError(result.error);
+        throw new ValidationError(`Invalid requirements file structure:\n${validationError.message}`, undefined, result.error);
+    }
+    return result.data;
+}
+//# sourceMappingURL=schemas.js.map

package/dist/schema/test-schema.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Quick test to verify the new YAML schema is valid and round-trips correctly.
+ */
+export {};
+//# sourceMappingURL=test-schema.d.ts.map

package/dist/schema/test-schema.js

@@ -0,0 +1,81 @@
+/**
+ * Quick test to verify the new YAML schema is valid and round-trips correctly.
+ */
+import { buildRequirementsMarkdown, parseRequirementsFile, buildMetadata } from './index.js';
+// Create test data
+const metadata = buildMetadata('test-project-123', 1);
+const testRequirements = [
+    {
+        id: 'REQ123',
+        label: 'requirement',
+        content: 'User can authenticate',
+        children: [
+            {
+                id: 'REQ123.0',
+                label: 'given',
+                content: 'user has valid credentials',
+                children: [],
+            },
+            {
+                id: 'REQ123.1',
+                label: 'when',
+                content: 'user submits login form',
+                children: [
+                    {
+                        id: 'REQ123.1.0',
+                        label: 'then',
+                        content: 'system validates credentials',
+                        children: [],
+                    },
+                    {
+                        id: 'REQ123.1.1',
+                        label: 'then',
+                        content: 'system creates session',
+                        children: [],
+                    },
+                ],
+            },
+            {
+                id: 'REQ123.2',
+                label: 'then',
+                content: 'user is redirected to dashboard',
+                children: [],
+            },
+        ],
+    },
+];
+console.log('=== Building Markdown ===\n');
+const markdown = buildRequirementsMarkdown(metadata, testRequirements);
+console.log(markdown);
+console.log('\n=== Parsing Markdown back ===\n');
+try {
+    const { metadata: parsedMeta, requirements: parsedReqs } = parseRequirementsFile(markdown);
+    console.log('Metadata:', JSON.stringify(parsedMeta, null, 2));
+    console.log('\nRequirements tree:');
+    function printTree(node, indent = 0) {
+        const spaces = '  '.repeat(indent);
+        console.log(`${spaces}${node.id}: ${node.label} → ${node.content}`);
+        for (const child of node.children) {
+            printTree(child, indent + 1);
+        }
+    }
+    for (const req of parsedReqs) {
+        printTree(req);
+    }
+    console.log('\n✅ Round-trip successful!');
+    // Verify structure
+    console.log('\n=== Verifying structure ===');
+    const req = parsedReqs[0];
+    console.log(`Root ID: ${req.id}`);
+    console.log(`Root label: ${req.label}`);
+    console.log(`Root content: ${req.content}`);
+    console.log(`Children count: ${req.children.length}`);
+    console.log(`First child ID: ${req.children[0].id}`);
+    console.log(`Second child has ${req.children[1].children.length} grandchildren`);
+    console.log(`First grandchild ID: ${req.children[1].children[0].id}`);
+}
+catch (error) {
+    console.error('❌ Failed to parse Markdown:', error);
+    process.exit(1);
+}
+//# sourceMappingURL=test-schema.js.map

package/dist/templates/antigravity-gemini.md

@@ -0,0 +1,3 @@
+<!-- BEGIN dotreq-requirements -->
+{{BEHAVIORAL_CORE}}
+<!-- END dotreq-requirements -->

package/dist/templates/antigravity-overview-rule.md

@@ -0,0 +1,3 @@
+<!-- BEGIN dotreq-overview -->
+{{OVERVIEW_CORE}}
+<!-- END dotreq-overview -->

package/dist/templates/antigravity-test-rule.md

@@ -0,0 +1,3 @@
+<!-- BEGIN dotreq-tests -->
+{{TEST_WRITING_CORE}}
+<!-- END dotreq-tests -->

package/dist/templates/behavioral-core.md

@@ -0,0 +1,25 @@
+# Requirements Capture
+
+ALWAYS ask about capturing requirements when the user requests new functionality (not bug fixes or refactoring).
+
+Ask: "Should we capture what this should do before we build it?"
+
+If yes, use the MCP tools for requirements writing.
+
+## Workflow
+
+1. **Ask questions** only if there are major gaps in expected behavior
+2. **Use requirements as alignment** - Get assumptions on paper quickly instead of playing twenty questions
+3. **Think MVP** - Don't expand scope without consulting the user
+4. **After building** - Suggest testing against the requirements using the project's standard testing tools
+
+Be helpful, consultative, and encouraging; not obstructive.
+
+## MCP Tools for Requirements
+
+- `create_requirement_document` - Get template with codebase-aware format guidance and style principles
+- `validate_requirements` - Check syntax before pushing (works offline)
+- `style_check` - Get AI feedback on writing quality and clarity
+- `push_requirements` - Sync to cloud (shows diff preview, then confirms)
+
+Note: Users can also explicitly trigger this workflow with `/capture-requirements`.