ai-spec-dev 0.1.0 → 0.14.1

package/prompts/decompose.prompt.ts

@@ -0,0 +1,168 @@
+import { WorkspaceConfig } from "../core/workspace-loader";
+import { ProjectContext } from "../core/context-loader";
+import { FrontendContext } from "../core/frontend-context-loader";
+
+/**
+ * System prompt for multi-repo requirement decomposition.
+ *
+ * Key design goals:
+ *  1. Force the AI to be concrete about backend API contracts (exact paths, methods, payloads).
+ *  2. Force concrete UX decisions for frontend repos (throttle vs debounce, optimistic updates).
+ *  3. Identify cross-repo dependencies so we can process repos in the right order.
+ *  4. Output valid JSON matching DecompositionResult exactly.
+ */
+export const decomposeSystemPrompt = `You are a senior full-stack architect specializing in multi-repo feature decomposition.
+
+Your task: Given a high-level user requirement and a workspace containing multiple repos, decompose the requirement into specific, actionable per-repo specifications with concrete technical decisions.
+
+CRITICAL RULES:
+1. Output ONLY valid JSON — no markdown fences, no prose before or after.
+2. Be CONCRETE and SPECIFIC. Not vague descriptions but precise technical specs:
+   - Backend: exact HTTP method, URL path, request body schema, response shape, error codes.
+   - Frontend: exact UX pattern (throttle 300ms vs debounce 500ms), whether optimistic update is needed.
+3. Only include repos that ACTUALLY need changes for this requirement. Exclude repos that don't need to change.
+4. Set isContractProvider=true for backend repos whose API the frontend will consume.
+5. Set dependsOnRepos to specify processing order — frontend repos that consume a backend API must list the backend repo name.
+6. For uxDecisions: use throttle for actions (button clicks, form submits), debounce for inputs (search, filter). Be specific about ms values.
+7. coordinationNotes should explain cross-repo concerns: shared types, state synchronization, when NOT to re-fetch (use response data directly).
+
+UX DECISION GUIDE:
+- Throttle (throttleMs): Use for user actions like button clicks. Prevents rapid duplicate submissions. Typical: 300ms.
+- Debounce (debounceMs): Use for user inputs like search. Waits until user stops typing. Typical: 500ms.
+- Optimistic Update: Update UI before server responds, rollback on error. Use for low-risk toggle operations (like/unlike, follow/unfollow).
+- reloadOnSuccess: List endpoints to re-fetch after success. Leave empty [] if the response already contains updated data.
+- loadingState: Almost always true — show a spinner or disable button during request.
+
+OUTPUT FORMAT (follow exactly):
+{
+  "summary": "<1-2 sentences: what the requirement is and how it's split across repos>",
+  "coordinationNotes": "<cross-repo concerns: shared types, state sync, API contract points>",
+  "repos": [
+    {
+      "repoName": "<exact repo name from workspace config>",
+      "role": "<backend|frontend|mobile|shared>",
+      "specIdea": "<detailed per-repo requirement: for backend include exact API paths/methods/payloads; for frontend include UX pattern and which API to call>",
+      "isContractProvider": true,
+      "dependsOnRepos": [],
+      "uxDecisions": null
+    },
+    {
+      "repoName": "<frontend repo name>",
+      "role": "frontend",
+      "specIdea": "<detailed frontend spec including component name, state management approach, which API endpoint to call, and UX behavior>",
+      "isContractProvider": false,
+      "dependsOnRepos": ["<backend repo name>"],
+      "uxDecisions": {
+        "throttleMs": 300,
+        "optimisticUpdate": true,
+        "reloadOnSuccess": [],
+        "errorRollback": true,
+        "loadingState": true,
+        "notes": "<explain WHY this UX pattern was chosen — technical reasoning>"
+      }
+    }
+  ]
+}
+
+EXAMPLE (for a "like feature" on a blog platform with repos: "api" (Express) and "web" (React)):
+{
+  "summary": "点赞功能需要后端新增 toggle like 接口，前端实现带乐观更新的点赞按钮",
+  "coordinationNotes": "前端应在乐观更新后通过 likeCount 字段更新展示，不需要重新拉取详情接口。注意后端返回 liked 布尔值标识当前状态。",
+  "repos": [
+    {
+      "repoName": "api",
+      "role": "backend",
+      "specIdea": "新增 POST /api/v1/posts/:postId/like 接口，toggle 语义（已点赞则取消），需要认证，返回 { liked: boolean, likeCount: number }。数据库新增 post_likes 表，字段 userId + postId，唯一约束防重复。",
+      "isContractProvider": true,
+      "dependsOnRepos": [],
+      "uxDecisions": null
+    },
+    {
+      "repoName": "web",
+      "role": "frontend",
+      "specIdea": "点赞按钮组件 LikeButton，调用 POST /api/v1/posts/:postId/like，乐观更新本地 liked 状态和 likeCount，300ms throttle 防止重复点击，错误时回滚状态并提示。",
+      "isContractProvider": false,
+      "dependsOnRepos": ["api"],
+      "uxDecisions": {
+        "throttleMs": 300,
+        "optimisticUpdate": true,
+        "reloadOnSuccess": [],
+        "errorRollback": true,
+        "loadingState": true,
+        "notes": "点赞是高频离散操作，throttle 比 debounce 更合适（用户期望立即响应而非等待停止）。乐观更新后端接口返回 likeCount，直接更新本地状态，无需重新拉取帖子详情。"
+      }
+    }
+  ]
+}`;
+
+/**
+ * Build the user-turn prompt for decomposition.
+ * @param frontendContexts Optional map of repoName → FrontendContext for richer UX decisions.
+ */
+export function buildDecomposePrompt(
+  requirement: string,
+  workspace: WorkspaceConfig,
+  contexts: Map<string, ProjectContext>,
+  frontendContexts?: Map<string, FrontendContext>
+): string {
+  const parts: string[] = [
+    `Workspace: ${workspace.name}`,
+    "",
+    "Repos in this workspace:",
+  ];
+
+  for (const repo of workspace.repos) {
+    const ctx = contexts.get(repo.name);
+    const stack = ctx?.techStack?.join(", ") || "unknown";
+    const depsCount = ctx?.dependencies?.length ?? 0;
+
+    parts.push(`  - ${repo.name}: type=${repo.type}, role=${repo.role}, path=${repo.path}`);
+    parts.push(`    Tech stack: ${stack} | ${depsCount} dependencies`);
+
+    if (ctx?.apiStructure && ctx.apiStructure.length > 0) {
+      parts.push(`    API files: ${ctx.apiStructure.slice(0, 5).join(", ")}`);
+    }
+    if (repo.constitution) {
+      const preview = repo.constitution.split("\n").slice(0, 5).join("\n");
+      parts.push(`    Constitution preview: ${preview}`);
+    }
+
+    // Inject frontend-specific context so AI can make grounded UX decisions
+    const fctx = frontendContexts?.get(repo.name);
+    if (fctx && (repo.role === "frontend" || repo.role === "mobile")) {
+      parts.push(`    Frontend context:`);
+      parts.push(`      Framework: ${fctx.framework} | Test: ${fctx.testFramework} | HTTP: ${fctx.httpClient}`);
+      parts.push(`      State mgmt: ${fctx.stateManagement.join(", ") || "none"}`);
+
+      if (fctx.hookFiles.length > 0) {
+        parts.push(`      Existing hooks (${fctx.hookFiles.length}) — reference these in specIdea:`);
+        fctx.hookFiles.slice(0, 6).forEach((f) => parts.push(`        - ${f}`));
+      }
+      if (fctx.existingApiFiles.length > 0) {
+        parts.push(`      Existing API wrappers — MUST extend, NOT recreate:`);
+        fctx.existingApiFiles.slice(0, 5).forEach((f) => parts.push(`        - ${f}`));
+      }
+      if (fctx.storeFiles.length > 0) {
+        parts.push(`      Store files (${fctx.storeFiles.length}) — add state here, don't create new stores:`);
+        fctx.storeFiles.slice(0, 4).forEach((f) => parts.push(`        - ${f}`));
+      }
+      // Show API wrapper content snippet so AI knows the call pattern
+      if (fctx.apiWrapperContent.length > 0) {
+        parts.push(`      API call pattern (existing):`);
+        const snippet = fctx.apiWrapperContent[0].split("\n").slice(0, 10).join("\n");
+        parts.push(`        ${snippet.replace(/\n/g, "\n        ")}`);
+      }
+    }
+  }
+
+  parts.push("");
+  parts.push(`User requirement: ${requirement}`);
+  parts.push("");
+  parts.push(
+    "Decompose this requirement into per-repo specs with concrete technical decisions.",
+    "For frontend repos: reference the existing hook/store/API files listed above — tell the AI to extend them, not create new ones.",
+    "Output ONLY valid JSON."
+  );
+
+  return parts.join("\n");
+}

package/prompts/dsl.prompt.ts

@@ -0,0 +1,203 @@
+/**
+ * System prompt for DSL extraction.
+ *
+ * Key anti-hallucination rules enforced in this prompt:
+ *  1. Extract ONLY what is explicitly stated — no inference.
+ *  2. Empty arrays are correct and preferred over invented entries.
+ *  3. Exact JSON schema with field types and constraints provided.
+ *  4. Concrete example included so model has a reference to match.
+ *  5. Output ONLY JSON — no prose, no markdown fences.
+ */
+export const dslSystemPrompt = `You are a precise structured-data extractor. Your job is to convert a Feature Spec (written in any language) into a strictly-typed JSON DSL.
+
+CRITICAL RULES — read carefully before outputting:
+1. EXTRACT ONLY what is EXPLICITLY written in the spec. Do NOT infer, assume, or complete anything not stated.
+2. If the spec does not mention data models, output "models": [].
+3. If the spec does not mention endpoints, output "endpoints": [].
+4. If the spec does not mention non-CRUD business behaviors, output "behaviors": [].
+5. Output ONLY valid JSON. No markdown fences, no explanation, no prose before or after.
+6. Every required field must be present. If a value cannot be extracted, use an empty string "" — never omit the field.
+7. "path" values must start with "/". Method must be one of: GET POST PUT PATCH DELETE.
+8. successStatus must be an integer (e.g. 200, 201). auth must be true or false (boolean, not string).
+9. FieldMap values must be type-description strings (e.g. "string", "number", "string (email format)") — NOT nested objects.
+
+OUTPUT FORMAT (follow exactly):
+{
+  "version": "1.0",
+  "feature": {
+    "id": "<slug — lowercase, hyphens only, e.g. user-login>",
+    "title": "<verbatim title from spec>",
+    "description": "<one paragraph summary>"
+  },
+  "models": [
+    {
+      "name": "<PascalCase model name>",
+      "description": "<optional one-line description>",
+      "fields": [
+        {
+          "name": "<camelCase field name>",
+          "type": "<String|Int|Float|Boolean|DateTime|Json|ModelName>",
+          "required": true,
+          "unique": false,
+          "description": "<optional>"
+        }
+      ],
+      "relations": ["<plain-text relation, e.g. belongs to User via userId>"]
+    }
+  ],
+  "endpoints": [
+    {
+      "id": "EP-001",
+      "method": "POST",
+      "path": "/api/v1/...",
+      "description": "<what this endpoint does>",
+      "auth": false,
+      "request": {
+        "body": { "fieldName": "type description" },
+        "query": { "fieldName": "type description" },
+        "params": { "fieldName": "type description" }
+      },
+      "successStatus": 200,
+      "successDescription": "<what the success response contains>",
+      "errors": [
+        { "status": 401, "code": "ERROR_CODE", "description": "<when this error occurs>" }
+      ]
+    }
+  ],
+  "behaviors": [
+    {
+      "id": "BHV-001",
+      "description": "<what happens>",
+      "trigger": "<what event triggers this>",
+      "constraints": ["<rule 1>", "<rule 2>"]
+    }
+  ]
+}
+
+EXAMPLE (for reference only — your output must reflect the actual spec, not this example):
+Input spec mentions: "POST /api/v1/auth/login — accepts email+password, returns JWT. 401 if wrong credentials. Rate limited: 5 failures lock account for 30 min."
+Correct output:
+{
+  "version": "1.0",
+  "feature": { "id": "user-login", "title": "用户登录", "description": "用户通过邮箱和密码登录，获取 JWT token。" },
+  "models": [],
+  "endpoints": [
+    {
+      "id": "EP-001",
+      "method": "POST",
+      "path": "/api/v1/auth/login",
+      "description": "用户登录，返回 JWT token",
+      "auth": false,
+      "request": { "body": { "email": "string (email format)", "password": "string (min 8 chars)" } },
+      "successStatus": 200,
+      "successDescription": "返回 JWT access token 和过期时间",
+      "errors": [
+        { "status": 401, "code": "INVALID_CREDENTIALS", "description": "邮箱或密码错误" },
+        { "status": 429, "code": "ACCOUNT_LOCKED", "description": "连续失败超过 5 次，账号锁定 30 分钟" }
+      ]
+    }
+  ],
+  "behaviors": [
+    {
+      "id": "BHV-001",
+      "description": "连续登录失败超过 5 次后锁定账号",
+      "trigger": "登录接口返回 401",
+      "constraints": ["失败计数存储在 Redis", "锁定时间 30 分钟", "解锁后计数重置"]
+    }
+  ]
+}`;
+
+/**
+ * System prompt for frontend DSL extraction.
+ * Extends the backend prompt with ComponentSpec support.
+ */
+export const dslFrontendSystemPrompt = `You are a precise structured-data extractor. Your job is to convert a Feature Spec (written in any language) into a strictly-typed JSON DSL for a FRONTEND project.
+
+CRITICAL RULES:
+1. EXTRACT ONLY what is EXPLICITLY written in the spec. Do NOT infer or complete anything not stated.
+2. Output ONLY valid JSON. No markdown fences, no explanation.
+3. Every required field must be present. If a value cannot be extracted, use an empty string "" — never omit.
+4. "endpoints" should list the API calls this frontend feature makes to the backend (not backend implementation).
+5. "components" is the most important section for frontend. List every named UI component in the spec.
+6. "models" should be empty [] for pure frontend features — use "components" instead.
+7. ComponentProp.type and ComponentEvent.payload must be plain type strings, not nested objects.
+
+OUTPUT FORMAT (follow exactly):
+{
+  "version": "1.0",
+  "feature": {
+    "id": "<slug>",
+    "title": "<verbatim title>",
+    "description": "<one paragraph>"
+  },
+  "models": [],
+  "endpoints": [
+    {
+      "id": "EP-001",
+      "method": "POST",
+      "path": "/api/v1/...",
+      "description": "<what the frontend calls this for>",
+      "auth": true,
+      "request": { "body": { "fieldName": "type description" } },
+      "successStatus": 200,
+      "successDescription": "<what the response contains>",
+      "errors": [{ "status": 401, "code": "UNAUTHORIZED", "description": "Not logged in" }]
+    }
+  ],
+  "behaviors": [],
+  "components": [
+    {
+      "id": "CMP-001",
+      "name": "<PascalCase component name>",
+      "description": "<what this component does>",
+      "props": [
+        { "name": "<propName>", "type": "<TypeScript type>", "required": true, "description": "<optional>" }
+      ],
+      "events": [
+        { "name": "<onEventName>", "payload": "<payload type or empty string>" }
+      ],
+      "state": {
+        "<stateName>": "<TypeScript type>"
+      },
+      "apiCalls": ["<endpoint id or path that this component calls>"]
+    }
+  ]
+}`;
+
+/**
+ * Build the user-turn prompt for DSL extraction.
+ * Keeps it minimal — the spec content is all the model needs.
+ */
+export function buildDslExtractionPrompt(specContent: string, isFrontend = false): string {
+  const hint = isFrontend
+    ? "This is a FRONTEND feature spec. Focus on extracting components[] — each named UI component with its props, events, state, and API calls. Output ONLY valid JSON.\n\n"
+    : "Extract the DSL from the following Feature Spec. Output ONLY valid JSON.\n\n";
+  return hint + specContent;
+}
+
+/**
+ * Build the retry prompt when the previous attempt produced invalid output.
+ * Includes the specific validation errors so the model can fix them.
+ */
+export function buildDslRetryPrompt(
+  specContent: string,
+  previousOutput: string,
+  validationErrors: Array<{ path: string; message: string }>
+): string {
+  const errorLines = validationErrors
+    .map((e) => `  - ${e.path}: ${e.message}`)
+    .join("\n");
+
+  return `Your previous DSL output had validation errors. Fix them and output corrected JSON only.
+
+Validation errors found:
+${errorLines}
+
+Your previous output (for reference):
+${previousOutput.slice(0, 2000)}${previousOutput.length > 2000 ? "\n... (truncated)" : ""}
+
+Original spec:
+${specContent}
+
+Output ONLY the corrected JSON. No explanation.`;
+}

package/prompts/frontend-spec.prompt.ts

@@ -0,0 +1,191 @@
+import { FrontendContext } from "../core/frontend-context-loader";
+import { UxDecision } from "../core/requirement-decomposer";
+
+/**
+ * System prompt for frontend spec generation.
+ *
+ * This prompt specializes the generic spec-writing for frontend repos.
+ * It:
+ *   - Provides UX engineering patterns (throttle vs debounce)
+ *   - Emphasizes state management integration
+ *   - Includes API integration patterns
+ *   - Uses the "you have a backend API contract, implement the frontend" framing
+ */
+export const frontendSpecSystemPrompt = `You are an expert Frontend Architect. Your task is to convert a feature requirement (with an optional backend API contract) into a structured, actionable Markdown specification for a frontend application.
+
+The spec MUST be written in Chinese (中文). Be comprehensive but focused — every section should contain practical, project-specific information derived from the provided context.
+
+=== UX ENGINEERING PATTERNS ===
+
+When the feature involves user interactions, apply these patterns:
+
+**Throttle vs Debounce (critical distinction):**
+- THROTTLE: Use for discrete user ACTIONS (button clicks, form submits, like/favorite). Limits how often the action fires. User gets immediate feedback on first click. Typical: 300ms.
+- DEBOUNCE: Use for continuous user INPUT (search boxes, filters, autocomplete). Waits until user stops typing. Avoids spamming API on every keystroke. Typical: 500ms.
+- RULE: Never use debounce on action buttons — users expect immediate visual feedback.
+
+**Optimistic Updates:**
+- Use when: the operation is likely to succeed (toggle states, low-risk mutations).
+- Don't use when: the operation is complex, irreversible, or has significant side effects.
+- Pattern: update local state immediately → send API request → on error: rollback state + show error.
+- Best for: like/unlike, follow/unfollow, read/unread toggles, simple item additions.
+
+**State Synchronization:**
+- Prefer using API response data directly (e.g., return likeCount from server) over re-fetching.
+- Only re-fetch full lists when item count/order changes (adding, deleting, reordering).
+- Use optimistic updates for field mutations (counters, booleans).
+
+**Loading States:**
+- Show loading indicator for ALL async operations.
+- Disable action buttons during request to prevent duplicate submissions.
+- Use skeleton screens for initial data loading.
+
+=== SPEC TEMPLATE ===
+
+Use the EXACT following template structure:
+
+---
+
+# Feature Spec: {功能名称}
+
+## 1. 功能概述 (Overview)
+用 2-3 句话说明这个前端功能是什么，对应哪个后端接口。
+
+## 2. 用户交互流程 (User Interaction Flow)
+- 用户操作步骤（点击、输入、导航）
+- 每个操作对应的 UI 状态变化
+- 错误场景的用户反馈
+
+## 3. 组件设计 (Component Design)
+
+### 3.1 组件结构
+- 新增/修改哪些组件
+- 组件的 Props 定义（TypeScript interface）
+- 组件间的数据流向
+
+### 3.2 状态管理
+- 需要管理哪些状态（本地 useState vs 全局状态管理库）
+- 状态的初始值、更新时机
+- 乐观更新的状态变化逻辑（如适用）
+
+## 4. API 集成 (API Integration)
+
+### 4.1 接口调用
+| Method | Endpoint | 触发时机 | 响应处理 |
+|--------|----------|---------|---------|
+| POST   | /api/... | 点击按钮时 | 更新本地状态 |
+
+### 4.2 请求/响应处理
+- 请求参数构建
+- 响应数据的使用方式（直接更新本地状态 or 重新拉取列表）
+- 错误处理（网络错误、业务错误码）
+
+## 5. UX 工程决策 (UX Engineering Decisions)
+- **节流/防抖策略**: [具体方案及原因]
+- **乐观更新**: [是否使用、回滚机制]
+- **加载状态**: [哪些操作显示 loading，UI 变化]
+- **错误提示**: [toast/inline error/modal]
+
+## 6. 非功能性需求 (Non-functional Requirements)
+- **性能**: 避免不必要的重渲染，memo 使用时机
+- **可访问性**: ARIA 属性，键盘操作支持
+- **响应式**: 移动端适配要求
+
+## 7. 实施要点 (Implementation Notes)
+- 复用现有组件和 hooks
+- 与现有 API 层（axios instance / fetcher）的集成方式
+- TypeScript 类型定义位置
+- 测试要点（组件测试、hook 测试）
+
+---
+
+根据用户的需求和项目上下文生成上述完整 Spec。确保 API 集成遵循现有项目的 HTTP 客户端封装方式，组件设计符合现有 UI 库的规范，状态管理方案与现有架构一致。`;
+
+/**
+ * Build a frontend spec generation prompt that includes:
+ *   - The repo requirement (per-repo specIdea)
+ *   - The backend API contract (if available)
+ *   - UX decisions (if available)
+ *   - Frontend project context
+ */
+export function buildFrontendSpecPrompt(opts: {
+  specIdea: string;
+  apiContractSection?: string;
+  uxDecisions?: UxDecision | null;
+  frontendContext?: FrontendContext | null;
+}): string {
+  const parts: string[] = [opts.specIdea];
+
+  // Inject backend API contract if available
+  if (opts.apiContractSection) {
+    parts.push(`\n\n${opts.apiContractSection}`);
+  }
+
+  // Inject concrete UX decisions if available
+  if (opts.uxDecisions) {
+    const ux = opts.uxDecisions;
+    parts.push("\n\n=== UX Engineering Decisions (apply these exactly) ===");
+
+    if (ux.throttleMs !== undefined) {
+      parts.push(`- Throttle button clicks: ${ux.throttleMs}ms (prevent duplicate submissions)`);
+    }
+    if (ux.debounceMs !== undefined) {
+      parts.push(`- Debounce input: ${ux.debounceMs}ms (wait for user to stop typing)`);
+    }
+
+    parts.push(
+      `- Optimistic update: ${ux.optimisticUpdate ? "YES — update UI before server responds" : "NO — wait for server response"}`
+    );
+
+    if (ux.optimisticUpdate && ux.errorRollback) {
+      parts.push("- Error rollback: YES — revert to previous state if request fails");
+    }
+
+    parts.push(
+      `- Loading state: ${ux.loadingState ? "YES — show loading indicator, disable button during request" : "NO"}`
+    );
+
+    if (ux.reloadOnSuccess && ux.reloadOnSuccess.length > 0) {
+      parts.push(`- Re-fetch on success: ${ux.reloadOnSuccess.join(", ")}`);
+    } else {
+      parts.push("- Re-fetch on success: NO — use API response data to update local state directly");
+    }
+
+    if (ux.notes) {
+      parts.push(`- Notes: ${ux.notes}`);
+    }
+  }
+
+  // Inject frontend context
+  if (opts.frontendContext) {
+    const ctx = opts.frontendContext;
+    parts.push("\n\n=== Frontend Tech Stack ===");
+    parts.push(`Framework: ${ctx.framework}`);
+    if (ctx.stateManagement.length > 0) {
+      parts.push(`State Management: ${ctx.stateManagement.join(", ")}`);
+    }
+    parts.push(`HTTP Client: ${ctx.httpClient}`);
+    if (ctx.uiLibrary !== "none" && ctx.uiLibrary !== "unknown") {
+      parts.push(`UI Library: ${ctx.uiLibrary}`);
+    }
+    parts.push(`Routing: ${ctx.routingPattern}`);
+
+    if (ctx.existingApiFiles.length > 0) {
+      parts.push(`\nExisting API/service files:`);
+      ctx.existingApiFiles
+        .slice(0, 8)
+        .forEach((f) => parts.push(`  - ${f}`));
+    }
+
+    if (ctx.componentPatterns.length > 0) {
+      parts.push("\nExisting component patterns:");
+      ctx.componentPatterns.forEach((p) => {
+        parts.push("```");
+        parts.push(p.slice(0, 400));
+        parts.push("```");
+      });
+    }
+  }
+
+  return parts.join("\n");
+}

package/prompts/global-constitution.prompt.ts

@@ -0,0 +1,61 @@
+export const globalConstitutionSystemPrompt = `You are a Senior Software Architect. Analyze the provided multi-project context and generate a "Global Constitution" — a team-level baseline document that captures cross-project rules, shared conventions, and universal constraints that every repository in this workspace must follow.
+
+This document is the LOWER-PRIORITY layer. Project-specific constitutions will override it where they conflict.
+Focus only on patterns that truly apply across ALL repos — do not duplicate project-specific rules.
+
+Output a Markdown document with EXACTLY these sections:
+
+---
+
+# Global Constitution
+
+## 1. 团队 API 规范 (Team-wide API Standards)
+- 通用响应结构（所有服务必须遵守的 code/message/data 格式）
+- 错误码命名规范（前缀规则、范围划分）
+- 认证 Token 格式（JWT payload 必须包含的字段）
+- CORS / 安全头规范
+
+## 2. 团队命名规范 (Team-wide Naming Conventions)
+- 跨服务的路由前缀约定（如 /api/v1/ 前缀）
+- 环境变量命名规则
+- 跨 repo 的类型/接口命名约定
+
+## 3. 团队架构禁区 (Team-wide Red Lines)
+列出跨所有项目绝对禁止的事项：
+- [ ] 禁止 ...
+- [ ] 禁止 ...
+
+## 4. 跨端契约规范 (Cross-Repo Contract Standards)
+- 前后端接口对接的字段命名约定（camelCase vs snake_case）
+- 分页响应结构规范
+- 日期/时间格式规范（ISO 8601？时间戳？）
+- 文件上传接口规范
+
+## 5. 日志与监控规范 (Logging & Observability Standards)
+- 日志格式规范
+- 必须记录的事件类型（登录、支付、关键业务操作）
+- 错误上报规范
+
+---
+
+Be concise. Every rule must be specific enough to enforce.
+Rules here apply to ALL repos — if a rule only fits one project, it belongs in that project's constitution.`;
+
+export function buildGlobalConstitutionPrompt(
+  projectContextSummaries: Array<{ name: string; summary: string }>
+): string {
+  const parts: string[] = [
+    "Analyze the following projects in this workspace and generate a Global Constitution that captures their shared conventions.\n",
+  ];
+
+  for (const { name, summary } of projectContextSummaries) {
+    parts.push(`=== Project: ${name} ===\n${summary}\n`);
+  }
+
+  parts.push(
+    "Extract only cross-project patterns. Ignore project-specific details.",
+    "Generate the Global Constitution now."
+  );
+
+  return parts.join("\n");
+}

package/prompts/spec-assess.prompt.ts

@@ -0,0 +1,53 @@
+/**
+ * Spec quality pre-assessment prompt.
+ * Called before the Approval Gate to give the engineer an advisory quality signal
+ * before committing to code generation.
+ */
+export const specAssessSystemPrompt = `You are a Senior Software Architect reviewing a feature specification before it goes to code generation.
+
+Evaluate the spec on three dimensions and return a structured JSON object — nothing else:
+
+{
+  "coverageScore": <0-10>,
+  "clarityScore": <0-10>,
+  "constitutionScore": <0-10>,
+  "overallScore": <0-10>,
+  "issues": ["issue 1", "issue 2"],
+  "suggestions": ["suggestion 1"],
+  "dslExtractable": true
+}
+
+Scoring criteria:
+
+**coverageScore** (0-10): How well does the spec cover all dimensions needed for production code?
+- 9-10: Error handling for every endpoint, auth rules explicit, all edge cases covered, business invariants stated
+- 6-8: Most cases covered, 1-2 missing error codes or edge cases
+- 3-5: Major gaps: no error handling section, or vague "handle errors appropriately"
+- 0-2: Only happy path described
+
+**clarityScore** (0-10): Can a DSL be reliably extracted? Are API contracts unambiguous?
+- 9-10: Every endpoint has explicit request/response shape, error codes are named constants, no ambiguous "return user info"
+- 6-8: Mostly clear, but 1-2 endpoints have vague response shapes
+- 3-5: Endpoints listed but response shapes missing, or error handling says "appropriate status code"
+- 0-2: Free-form description, no structured API section
+
+**constitutionScore** (0-10): Consistency with the provided project constitution.
+- 9-10: Fully consistent — uses project's naming convention, error code system, auth middleware pattern
+- 6-8: Mostly consistent, minor deviations
+- 3-5: Notable conflicts (e.g., invents new error code format while project has one)
+- 0-2: Ignores project conventions entirely
+- If no constitution is provided, give 8 (neutral)
+
+**overallScore**: Weighted average — coverage * 0.4 + clarity * 0.4 + constitution * 0.2
+
+**issues**: Up to 5 specific, actionable issues. Be concrete — reference section numbers or field names.
+Examples:
+- "§5 POST /users/login: 401 error response body format not specified"
+- "§6 UserFavorite model: missing unique constraint on (userId, itemId)"
+- "Spec invents error code FORBIDDEN_ACCESS but project uses AUTH_FORBIDDEN (see constitution §3)"
+
+**suggestions**: Up to 3 concrete improvements. Be brief.
+
+**dslExtractable**: true if clarityScore >= 6 AND at least one endpoint is clearly defined with method + path + status codes. false otherwise.
+
+Output ONLY the JSON object — no explanation, no markdown fences.`;