popeye-cli 2.0.0 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (161) hide show
  1. package/CHANGELOG.md +55 -0
  2. package/CONTRIBUTING.md +23 -2
  3. package/README.md +47 -18
  4. package/dist/adapters/gemini.js +3 -3
  5. package/dist/adapters/openai.js +2 -2
  6. package/dist/adapters/openai.js.map +1 -1
  7. package/dist/auth/gemini.js +1 -1
  8. package/dist/cli/commands/create.d.ts.map +1 -1
  9. package/dist/cli/commands/create.js +11 -5
  10. package/dist/cli/commands/create.js.map +1 -1
  11. package/dist/cli/commands/resume.d.ts.map +1 -1
  12. package/dist/cli/commands/resume.js +9 -1
  13. package/dist/cli/commands/resume.js.map +1 -1
  14. package/dist/cli/interactive.d.ts.map +1 -1
  15. package/dist/cli/interactive.js +33 -4
  16. package/dist/cli/interactive.js.map +1 -1
  17. package/dist/config/defaults.d.ts.map +1 -1
  18. package/dist/config/defaults.js +7 -2
  19. package/dist/config/defaults.js.map +1 -1
  20. package/dist/config/index.d.ts +1 -7
  21. package/dist/config/index.d.ts.map +1 -1
  22. package/dist/config/popeye-md.d.ts +32 -0
  23. package/dist/config/popeye-md.d.ts.map +1 -0
  24. package/dist/config/popeye-md.js +111 -0
  25. package/dist/config/popeye-md.js.map +1 -0
  26. package/dist/config/schema.d.ts +3 -21
  27. package/dist/config/schema.d.ts.map +1 -1
  28. package/dist/config/schema.js +21 -8
  29. package/dist/config/schema.js.map +1 -1
  30. package/dist/generators/all.d.ts.map +1 -1
  31. package/dist/generators/all.js +23 -1
  32. package/dist/generators/all.js.map +1 -1
  33. package/dist/pipeline/artifact-manager.d.ts.map +1 -1
  34. package/dist/pipeline/artifact-manager.js +3 -0
  35. package/dist/pipeline/artifact-manager.js.map +1 -1
  36. package/dist/pipeline/bridges/review-bridge.d.ts +70 -0
  37. package/dist/pipeline/bridges/review-bridge.d.ts.map +1 -0
  38. package/dist/pipeline/bridges/review-bridge.js +266 -0
  39. package/dist/pipeline/bridges/review-bridge.js.map +1 -0
  40. package/dist/pipeline/consensus/consensus-runner.js +3 -3
  41. package/dist/pipeline/consensus/consensus-runner.js.map +1 -1
  42. package/dist/pipeline/gate-engine.js +1 -1
  43. package/dist/pipeline/gate-engine.js.map +1 -1
  44. package/dist/pipeline/migration.d.ts.map +1 -1
  45. package/dist/pipeline/migration.js +3 -26
  46. package/dist/pipeline/migration.js.map +1 -1
  47. package/dist/pipeline/orchestrator.d.ts +2 -0
  48. package/dist/pipeline/orchestrator.d.ts.map +1 -1
  49. package/dist/pipeline/orchestrator.js +10 -1
  50. package/dist/pipeline/orchestrator.js.map +1 -1
  51. package/dist/pipeline/phases/implementation.d.ts.map +1 -1
  52. package/dist/pipeline/phases/implementation.js +5 -2
  53. package/dist/pipeline/phases/implementation.js.map +1 -1
  54. package/dist/pipeline/phases/intake.d.ts +1 -0
  55. package/dist/pipeline/phases/intake.d.ts.map +1 -1
  56. package/dist/pipeline/phases/intake.js +56 -8
  57. package/dist/pipeline/phases/intake.js.map +1 -1
  58. package/dist/pipeline/phases/recovery-loop.d.ts.map +1 -1
  59. package/dist/pipeline/phases/recovery-loop.js +2 -0
  60. package/dist/pipeline/phases/recovery-loop.js.map +1 -1
  61. package/dist/pipeline/phases/role-planning.d.ts.map +1 -1
  62. package/dist/pipeline/phases/role-planning.js +2 -3
  63. package/dist/pipeline/phases/role-planning.js.map +1 -1
  64. package/dist/pipeline/skills/constitution-generator.d.ts +51 -0
  65. package/dist/pipeline/skills/constitution-generator.d.ts.map +1 -0
  66. package/dist/pipeline/skills/constitution-generator.js +210 -0
  67. package/dist/pipeline/skills/constitution-generator.js.map +1 -0
  68. package/dist/pipeline/skills/generator.d.ts +65 -0
  69. package/dist/pipeline/skills/generator.d.ts.map +1 -0
  70. package/dist/pipeline/skills/generator.js +221 -0
  71. package/dist/pipeline/skills/generator.js.map +1 -0
  72. package/dist/pipeline/skills/role-map.d.ts +38 -0
  73. package/dist/pipeline/skills/role-map.d.ts.map +1 -0
  74. package/dist/pipeline/skills/role-map.js +234 -0
  75. package/dist/pipeline/skills/role-map.js.map +1 -0
  76. package/dist/pipeline/skills/types.d.ts +47 -0
  77. package/dist/pipeline/skills/types.d.ts.map +1 -0
  78. package/dist/pipeline/skills/types.js +5 -0
  79. package/dist/pipeline/skills/types.js.map +1 -0
  80. package/dist/pipeline/type-defs/artifacts.d.ts +10 -0
  81. package/dist/pipeline/type-defs/artifacts.d.ts.map +1 -1
  82. package/dist/pipeline/type-defs/artifacts.js +2 -0
  83. package/dist/pipeline/type-defs/artifacts.js.map +1 -1
  84. package/dist/pipeline/type-defs/audit.d.ts +6 -0
  85. package/dist/pipeline/type-defs/audit.d.ts.map +1 -1
  86. package/dist/pipeline/type-defs/checks.d.ts +2 -0
  87. package/dist/pipeline/type-defs/checks.d.ts.map +1 -1
  88. package/dist/pipeline/type-defs/packets.d.ts +30 -0
  89. package/dist/pipeline/type-defs/packets.d.ts.map +1 -1
  90. package/dist/pipeline/type-defs/state.d.ts +11 -0
  91. package/dist/pipeline/type-defs/state.d.ts.map +1 -1
  92. package/dist/pipeline/type-defs/state.js +2 -0
  93. package/dist/pipeline/type-defs/state.js.map +1 -1
  94. package/dist/types/consensus.d.ts +5 -1
  95. package/dist/types/consensus.d.ts.map +1 -1
  96. package/dist/types/consensus.js +15 -4
  97. package/dist/types/consensus.js.map +1 -1
  98. package/dist/types/index.d.ts +1 -1
  99. package/dist/types/index.d.ts.map +1 -1
  100. package/dist/types/index.js +1 -1
  101. package/dist/types/index.js.map +1 -1
  102. package/dist/types/project.d.ts +1 -1
  103. package/dist/types/project.d.ts.map +1 -1
  104. package/dist/types/project.js +39 -10
  105. package/dist/types/project.js.map +1 -1
  106. package/dist/types/workflow.d.ts +1 -7
  107. package/dist/types/workflow.d.ts.map +1 -1
  108. package/dist/types/workflow.js +1 -1
  109. package/dist/types/workflow.js.map +1 -1
  110. package/dist/upgrade/handlers.js +5 -5
  111. package/dist/upgrade/handlers.js.map +1 -1
  112. package/dist/workflow/index.d.ts.map +1 -1
  113. package/dist/workflow/index.js +18 -14
  114. package/dist/workflow/index.js.map +1 -1
  115. package/dist/workflow/website-strategy.js +1 -1
  116. package/dist/workflow/website-strategy.js.map +1 -1
  117. package/package.json +1 -1
  118. package/src/adapters/gemini.ts +3 -3
  119. package/src/adapters/openai.ts +2 -2
  120. package/src/auth/gemini.ts +1 -1
  121. package/src/cli/commands/create.ts +12 -6
  122. package/src/cli/commands/resume.ts +9 -1
  123. package/src/cli/interactive.ts +36 -4
  124. package/src/config/defaults.ts +7 -2
  125. package/src/config/popeye-md.ts +139 -0
  126. package/src/config/schema.ts +21 -8
  127. package/src/generators/all.ts +23 -1
  128. package/src/pipeline/artifact-manager.ts +3 -0
  129. package/src/pipeline/bridges/review-bridge.ts +371 -0
  130. package/src/pipeline/consensus/consensus-runner.ts +3 -3
  131. package/src/pipeline/gate-engine.ts +1 -1
  132. package/src/pipeline/migration.ts +5 -30
  133. package/src/pipeline/orchestrator.ts +14 -0
  134. package/src/pipeline/phases/implementation.ts +6 -2
  135. package/src/pipeline/phases/intake.ts +73 -10
  136. package/src/pipeline/phases/recovery-loop.ts +2 -0
  137. package/src/pipeline/phases/role-planning.ts +2 -3
  138. package/src/pipeline/skills/constitution-generator.ts +236 -0
  139. package/src/pipeline/skills/generator.ts +287 -0
  140. package/src/pipeline/skills/role-map.ts +248 -0
  141. package/src/pipeline/skills/types.ts +53 -0
  142. package/src/pipeline/type-defs/artifacts.ts +2 -0
  143. package/src/pipeline/type-defs/state.ts +2 -0
  144. package/src/types/consensus.ts +16 -4
  145. package/src/types/index.ts +1 -0
  146. package/src/types/project.ts +39 -10
  147. package/src/types/workflow.ts +1 -1
  148. package/src/upgrade/handlers.ts +5 -5
  149. package/src/workflow/index.ts +18 -14
  150. package/src/workflow/website-strategy.ts +1 -1
  151. package/tests/cli/model-command.test.ts +19 -9
  152. package/tests/config/config.test.ts +3 -3
  153. package/tests/config/popeye-md.test.ts +168 -0
  154. package/tests/pipeline/bridges/review-bridge.test.ts +243 -0
  155. package/tests/pipeline/migration.test.ts +4 -3
  156. package/tests/pipeline/session-guidance.test.ts +205 -0
  157. package/tests/pipeline/skills/constitution-generator.test.ts +201 -0
  158. package/tests/pipeline/skills/generator.test.ts +213 -0
  159. package/tests/pipeline/skills/role-map.test.ts +198 -0
  160. package/tests/types/consensus.test.ts +1 -1
  161. package/tests/workflow/pipeline-bootstrap.test.ts +162 -0
@@ -0,0 +1,287 @@
1
+ /**
2
+ * Project-specific skill generation.
3
+ * Uses a single AI call to generate tailored system prompts for active roles,
4
+ * then writes them as .md files with YAML frontmatter to the project's skills/ dir.
5
+ * Falls back to defaults with project-specific constraints on AI failure.
6
+ */
7
+
8
+ import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
9
+ import { join } from 'node:path';
10
+ import { z } from 'zod';
11
+
12
+ import type { PipelineRole } from '../types.js';
13
+ import type { ArtifactManager } from '../artifact-manager.js';
14
+ import { DEFAULT_SKILLS } from './defaults.js';
15
+ import { inferTechStack, getTemplateConstraints } from './role-map.js';
16
+ import type { SkillGenerationContext, SkillsGenerationMarker, TechStack } from './types.js';
17
+
18
+ // ─── Constants ──────────────────────────────────────────
19
+
20
+ const PIPELINE_VERSION = '1.0';
21
+ const MARKER_FILENAME = '.popeye-skills-generated.json';
22
+
23
+ /** Zod schema for validating AI-generated skill prompts */
24
+ const SkillPromptsResponseSchema = z.record(z.string(), z.string());
25
+
26
+ // ─── Public API ─────────────────────────────────────────
27
+
28
+ /**
29
+ * Generate project-specific skill .md files for all active roles.
30
+ * Skips roles that already have a .md file in the skills directory.
31
+ * Stores the raw AI response as a skill_generation_log artifact.
32
+ *
33
+ * @param context - Skill generation context with project details
34
+ * @param artifactManager - Optional artifact manager for logging
35
+ */
36
+ export async function generateProjectSkills(
37
+ context: SkillGenerationContext,
38
+ artifactManager?: ArtifactManager,
39
+ ): Promise<void> {
40
+ const { activeRoles, skillsDir } = context;
41
+
42
+ // Ensure skills directory exists
43
+ if (!existsSync(skillsDir)) {
44
+ mkdirSync(skillsDir, { recursive: true });
45
+ }
46
+
47
+ // Determine which roles need generation
48
+ const rolesToGenerate = activeRoles.filter((role) => shouldGenerateSkill(skillsDir, role));
49
+
50
+ if (rolesToGenerate.length === 0) {
51
+ return;
52
+ }
53
+
54
+ // Infer tech stack
55
+ const techStack = inferTechStack(context.language, context.snapshot, context.expandedSpec);
56
+
57
+ // Attempt AI generation
58
+ let aiPrompts: Record<string, string> = {};
59
+ let aiGenerated = false;
60
+
61
+ try {
62
+ const prompt = buildSkillGenPrompt(context, rolesToGenerate, techStack);
63
+ const { createClient } = await import('../../adapters/openai.js');
64
+ const client = await createClient();
65
+
66
+ const completion = await client.chat.completions.create({
67
+ model: 'gpt-4.1',
68
+ messages: [{ role: 'user', content: prompt }],
69
+ temperature: 0.4,
70
+ max_tokens: 4096,
71
+ });
72
+
73
+ const rawResponse = completion.choices[0]?.message?.content ?? '';
74
+
75
+ // Store raw AI response as artifact
76
+ if (artifactManager) {
77
+ artifactManager.createAndStoreText(
78
+ 'skill_generation_log',
79
+ rawResponse,
80
+ 'INTAKE',
81
+ );
82
+ }
83
+
84
+ aiPrompts = parseSkillPrompts(rawResponse, rolesToGenerate);
85
+ aiGenerated = Object.keys(aiPrompts).length > 0;
86
+ } catch {
87
+ // AI failure is non-fatal — fall through to defaults with project constraints
88
+ aiGenerated = false;
89
+ }
90
+
91
+ // Write skill files
92
+ for (const role of rolesToGenerate) {
93
+ const defaultSkill = DEFAULT_SKILLS[role];
94
+ const systemPrompt = aiPrompts[role] ?? defaultSkill?.systemPrompt ?? '';
95
+ const constraints = getTemplateConstraints(role, techStack);
96
+ const allConstraints = [
97
+ ...(defaultSkill?.constraints ?? []),
98
+ ...constraints,
99
+ ];
100
+ // Deduplicate constraints
101
+ const uniqueConstraints = [...new Set(allConstraints)];
102
+ const dependsOn = defaultSkill?.depends_on ?? [];
103
+ const requiredOutputs = defaultSkill?.required_outputs ?? [];
104
+
105
+ const markdown = renderSkillMarkdown(
106
+ role,
107
+ systemPrompt,
108
+ uniqueConstraints,
109
+ requiredOutputs,
110
+ dependsOn,
111
+ );
112
+
113
+ const filePath = join(skillsDir, `${role}.md`);
114
+ writeFileSync(filePath, markdown, 'utf-8');
115
+ }
116
+
117
+ // Write generation marker
118
+ const marker: SkillsGenerationMarker = {
119
+ timestamp: new Date().toISOString(),
120
+ pipelineVersion: PIPELINE_VERSION,
121
+ activeRoles: activeRoles.map(String),
122
+ techStack,
123
+ aiGenerated,
124
+ };
125
+ writeGenerationMarker(skillsDir, marker);
126
+ }
127
+
128
+ // ─── Skip Logic ─────────────────────────────────────────
129
+
130
+ /**
131
+ * Check if a skill file should be generated for a role.
132
+ * Returns false if the role already has a .md file (hand-written or prior run).
133
+ *
134
+ * @param skillsDir - Path to the skills directory
135
+ * @param role - Pipeline role to check
136
+ * @returns true if the role needs a generated skill file
137
+ */
138
+ export function shouldGenerateSkill(skillsDir: string, role: PipelineRole): boolean {
139
+ const mdPath = join(skillsDir, `${role}.md`);
140
+ return !existsSync(mdPath);
141
+ }
142
+
143
+ // ─── Prompt Building ────────────────────────────────────
144
+
145
+ /**
146
+ * Build the AI prompt that requests system prompts for all roles at once.
147
+ *
148
+ * @param context - Generation context
149
+ * @param roles - Roles needing prompts
150
+ * @param techStack - Inferred tech stack
151
+ * @returns Formatted prompt string
152
+ */
153
+ export function buildSkillGenPrompt(
154
+ context: SkillGenerationContext,
155
+ roles: PipelineRole[],
156
+ techStack: TechStack,
157
+ ): string {
158
+ const techDesc = Object.entries(techStack)
159
+ .filter(([, v]) => v)
160
+ .map(([k, v]) => `- ${k}: ${v}`)
161
+ .join('\n');
162
+
163
+ const roleDescriptions = roles.map((role) => {
164
+ const defaultSkill = DEFAULT_SKILLS[role];
165
+ return `- ${role}: ${defaultSkill?.systemPrompt.slice(0, 100) ?? 'Pipeline role'}...`;
166
+ }).join('\n');
167
+
168
+ return `You are generating project-specific skill definitions for an AI pipeline.
169
+
170
+ ## Project: ${context.projectName}
171
+ ## Tech Stack:
172
+ ${techDesc}
173
+
174
+ ## Expanded Specification (summary):
175
+ ${context.expandedSpec.slice(0, 3000)}
176
+
177
+ ${context.sessionGuidance ? `## Session Guidance:\n${context.sessionGuidance.slice(0, 1000)}\n` : ''}
178
+ ## Roles needing prompts:
179
+ ${roleDescriptions}
180
+
181
+ ## Instructions:
182
+ Generate a tailored system prompt for each role listed above. Each prompt should:
183
+ 1. Reference the specific tech stack (e.g., "FastAPI async endpoints" not "API endpoints")
184
+ 2. Reference the project name
185
+ 3. Be 3-6 sentences
186
+ 4. Focus on the role's responsibilities in this specific project context
187
+
188
+ Respond with ONLY a JSON object mapping role names to their system prompts. Example:
189
+ {"BACKEND_PROGRAMMER": "You are the Backend Programmer for ProjectName. You implement..."}
190
+
191
+ JSON response:`;
192
+ }
193
+
194
+ // ─── Response Parsing ───────────────────────────────────
195
+
196
+ /**
197
+ * Parse and validate the AI response as a JSON record of role prompts.
198
+ * Falls back per-role: missing or invalid entries are excluded.
199
+ *
200
+ * @param response - Raw AI response text
201
+ * @param expectedRoles - Roles we requested prompts for
202
+ * @returns Validated record of role -> system prompt
203
+ */
204
+ export function parseSkillPrompts(
205
+ response: string,
206
+ expectedRoles: PipelineRole[],
207
+ ): Record<string, string> {
208
+ try {
209
+ // Extract JSON from response (may be wrapped in markdown code fences)
210
+ const jsonMatch = response.match(/\{[\s\S]*\}/);
211
+ if (!jsonMatch) return {};
212
+
213
+ const parsed = JSON.parse(jsonMatch[0]);
214
+ const validated = SkillPromptsResponseSchema.parse(parsed);
215
+
216
+ // Filter to only expected roles with non-empty prompts
217
+ const result: Record<string, string> = {};
218
+ for (const role of expectedRoles) {
219
+ if (validated[role] && validated[role].trim().length > 10) {
220
+ result[role] = validated[role].trim();
221
+ }
222
+ }
223
+ return result;
224
+ } catch {
225
+ return {};
226
+ }
227
+ }
228
+
229
+ // ─── Markdown Rendering ─────────────────────────────────
230
+
231
+ /**
232
+ * Render a skill definition as a Markdown file with YAML frontmatter.
233
+ * Format matches what the SkillLoader's parseSkillMarkdown() expects.
234
+ *
235
+ * @param role - Pipeline role
236
+ * @param systemPrompt - The system prompt body
237
+ * @param constraints - Combined constraint identifiers
238
+ * @param requiredOutputs - Required output types
239
+ * @param dependsOn - Upstream role dependencies
240
+ * @returns Complete markdown string
241
+ */
242
+ export function renderSkillMarkdown(
243
+ role: PipelineRole,
244
+ systemPrompt: string,
245
+ constraints: string[],
246
+ requiredOutputs: string[],
247
+ dependsOn: PipelineRole[],
248
+ ): string {
249
+ const lines: string[] = [
250
+ '---',
251
+ `role: ${role}`,
252
+ 'version: 1.0-project',
253
+ 'required_outputs:',
254
+ ...requiredOutputs.map((o) => ` - ${o}`),
255
+ 'constraints:',
256
+ ...constraints.map((c) => ` - ${c}`),
257
+ ];
258
+
259
+ if (dependsOn.length > 0) {
260
+ lines.push('depends_on:');
261
+ for (const dep of dependsOn) {
262
+ lines.push(` - ${dep}`);
263
+ }
264
+ }
265
+
266
+ lines.push('---');
267
+ lines.push(systemPrompt);
268
+ lines.push('');
269
+
270
+ return lines.join('\n');
271
+ }
272
+
273
+ // ─── Marker File ────────────────────────────────────────
274
+
275
+ /**
276
+ * Write the generation marker file to track what was generated.
277
+ *
278
+ * @param skillsDir - Path to the skills directory
279
+ * @param marker - Marker data to persist
280
+ */
281
+ export function writeGenerationMarker(
282
+ skillsDir: string,
283
+ marker: SkillsGenerationMarker,
284
+ ): void {
285
+ const markerPath = join(skillsDir, MARKER_FILENAME);
286
+ writeFileSync(markerPath, JSON.stringify(marker, null, 2), 'utf-8');
287
+ }
@@ -0,0 +1,248 @@
1
+ /**
2
+ * Shared role mapping and tech stack inference.
3
+ * Extracted from migration.ts to be the single source of truth for
4
+ * language-to-role mapping and tech stack detection.
5
+ */
6
+
7
+ import type { OutputLanguage } from '../../types/project.js';
8
+ import type { PipelineRole, RepoSnapshot } from '../types.js';
9
+ import type { TechStack } from './types.js';
10
+
11
+ // ─── Role Categories ────────────────────────────────────
12
+
13
+ /** Roles that always participate regardless of language */
14
+ export const SUPPORT_ROLES: PipelineRole[] = [
15
+ 'DISPATCHER',
16
+ 'ARCHITECT',
17
+ 'QA_TESTER',
18
+ 'REVIEWER',
19
+ 'ARBITRATOR',
20
+ 'DEBUGGER',
21
+ 'AUDITOR',
22
+ 'JOURNALIST',
23
+ 'RELEASE_MANAGER',
24
+ ];
25
+
26
+ /** Language-specific implementation role sets */
27
+ const IMPLEMENTATION_ROLE_MAP: Record<OutputLanguage, PipelineRole[]> = {
28
+ python: ['DB_EXPERT', 'BACKEND_PROGRAMMER'],
29
+ typescript: ['FRONTEND_PROGRAMMER', 'UI_UX_SPECIALIST'],
30
+ fullstack: ['DB_EXPERT', 'BACKEND_PROGRAMMER', 'FRONTEND_PROGRAMMER', 'UI_UX_SPECIALIST'],
31
+ website: ['WEBSITE_PROGRAMMER', 'UI_UX_SPECIALIST', 'MARKETING_EXPERT', 'SOCIAL_EXPERT'],
32
+ all: [
33
+ 'DB_EXPERT', 'BACKEND_PROGRAMMER', 'FRONTEND_PROGRAMMER',
34
+ 'WEBSITE_PROGRAMMER', 'UI_UX_SPECIALIST', 'MARKETING_EXPERT', 'SOCIAL_EXPERT',
35
+ ],
36
+ };
37
+
38
+ /** All possible implementation roles across all languages */
39
+ export const IMPLEMENTATION_ROLES: PipelineRole[] = [
40
+ 'DB_EXPERT', 'BACKEND_PROGRAMMER', 'FRONTEND_PROGRAMMER',
41
+ 'WEBSITE_PROGRAMMER', 'UI_UX_SPECIALIST', 'MARKETING_EXPERT', 'SOCIAL_EXPERT',
42
+ ];
43
+
44
+ // ─── Active Role Selection ──────────────────────────────
45
+
46
+ /**
47
+ * Determine the active roles for a given language.
48
+ *
49
+ * @param language - The project's output language
50
+ * @returns All roles (support + implementation) active for this language
51
+ */
52
+ export function getActiveRoles(language: OutputLanguage): PipelineRole[] {
53
+ const implRoles = IMPLEMENTATION_ROLE_MAP[language] ?? ['BACKEND_PROGRAMMER'];
54
+ return [...SUPPORT_ROLES, ...implRoles];
55
+ }
56
+
57
+ // ─── Tech Stack Inference ───────────────────────────────
58
+
59
+ /** Framework detection patterns for snapshot config key_fields */
60
+ const FRAMEWORK_PATTERNS: Record<string, Partial<TechStack>> = {
61
+ fastapi: { backend: 'FastAPI' },
62
+ django: { backend: 'Django' },
63
+ flask: { backend: 'Flask' },
64
+ express: { backend: 'Express' },
65
+ nestjs: { backend: 'NestJS' },
66
+ 'next': { frontend: 'Next.js' },
67
+ nuxt: { frontend: 'Nuxt' },
68
+ react: { frontend: 'React' },
69
+ vue: { frontend: 'Vue' },
70
+ svelte: { frontend: 'SvelteKit' },
71
+ angular: { frontend: 'Angular' },
72
+ sqlalchemy: { orm: 'SQLAlchemy' },
73
+ prisma: { orm: 'Prisma' },
74
+ drizzle: { orm: 'Drizzle' },
75
+ typeorm: { orm: 'TypeORM' },
76
+ sequelize: { orm: 'Sequelize' },
77
+ postgresql: { database: 'PostgreSQL' },
78
+ postgres: { database: 'PostgreSQL' },
79
+ mysql: { database: 'MySQL' },
80
+ sqlite: { database: 'SQLite' },
81
+ mongodb: { database: 'MongoDB' },
82
+ mongoose: { database: 'MongoDB' },
83
+ pytest: { testing: 'Pytest' },
84
+ vitest: { testing: 'Vitest' },
85
+ jest: { testing: 'Jest' },
86
+ mocha: { testing: 'Mocha' },
87
+ };
88
+
89
+ /** Language-based defaults when no signals are available */
90
+ const LANGUAGE_DEFAULTS: Record<OutputLanguage, TechStack> = {
91
+ python: {
92
+ language: 'Python 3.11+',
93
+ backend: 'FastAPI',
94
+ database: 'PostgreSQL',
95
+ orm: 'SQLAlchemy',
96
+ testing: 'Pytest',
97
+ },
98
+ typescript: {
99
+ language: 'TypeScript 5.x',
100
+ frontend: 'React + Vite',
101
+ testing: 'Vitest',
102
+ },
103
+ fullstack: {
104
+ language: 'TypeScript 5.x / Python 3.11+',
105
+ backend: 'FastAPI',
106
+ frontend: 'React + Vite',
107
+ database: 'PostgreSQL',
108
+ orm: 'SQLAlchemy',
109
+ testing: 'Vitest + Pytest',
110
+ },
111
+ website: {
112
+ language: 'TypeScript 5.x',
113
+ frontend: 'Next.js',
114
+ testing: 'Vitest',
115
+ },
116
+ all: {
117
+ language: 'TypeScript 5.x / Python 3.11+',
118
+ backend: 'FastAPI',
119
+ frontend: 'React + Vite',
120
+ database: 'PostgreSQL',
121
+ orm: 'SQLAlchemy',
122
+ testing: 'Vitest + Pytest',
123
+ },
124
+ };
125
+
126
+ /**
127
+ * Infer the project's tech stack from available signals.
128
+ * Priority: snapshot deps > spec mentions > language defaults.
129
+ *
130
+ * @param language - The project's output language
131
+ * @param snapshot - Optional repo snapshot with config file data
132
+ * @param expandedSpec - Optional expanded specification text
133
+ * @returns Inferred tech stack
134
+ */
135
+ export function inferTechStack(
136
+ language: OutputLanguage,
137
+ snapshot?: RepoSnapshot,
138
+ expandedSpec?: string,
139
+ ): TechStack {
140
+ const defaults = LANGUAGE_DEFAULTS[language] ?? LANGUAGE_DEFAULTS.python;
141
+ const detected: TechStack = { language: defaults.language };
142
+
143
+ // 1. Scan snapshot config_files key_fields for dependency signals
144
+ // Only set each field once — first match wins per field.
145
+ if (snapshot?.config_files) {
146
+ for (const configFile of snapshot.config_files) {
147
+ const keyFieldsStr = JSON.stringify(configFile.key_fields).toLowerCase();
148
+ for (const [pattern, stack] of Object.entries(FRAMEWORK_PATTERNS)) {
149
+ if (keyFieldsStr.includes(pattern)) {
150
+ for (const [key, value] of Object.entries(stack)) {
151
+ if (!detected[key as keyof TechStack]) {
152
+ (detected as Record<string, string>)[key] = value;
153
+ }
154
+ }
155
+ }
156
+ }
157
+ }
158
+ }
159
+
160
+ // 2. Use snapshot test_framework / build_tool if available
161
+ if (snapshot?.test_framework) {
162
+ const tfLower = snapshot.test_framework.toLowerCase();
163
+ for (const [pattern, stack] of Object.entries(FRAMEWORK_PATTERNS)) {
164
+ if (tfLower.includes(pattern) && stack.testing) {
165
+ detected.testing = stack.testing;
166
+ }
167
+ }
168
+ }
169
+
170
+ // 3. Scan expandedSpec for framework mentions
171
+ if (expandedSpec) {
172
+ const specLower = expandedSpec.toLowerCase();
173
+ for (const [pattern, stack] of Object.entries(FRAMEWORK_PATTERNS)) {
174
+ if (specLower.includes(pattern)) {
175
+ // Only fill in gaps — snapshot deps take priority
176
+ for (const [key, value] of Object.entries(stack)) {
177
+ if (!detected[key as keyof TechStack]) {
178
+ (detected as Record<string, string>)[key] = value;
179
+ }
180
+ }
181
+ }
182
+ }
183
+ }
184
+
185
+ // 4. Fill remaining gaps with language defaults
186
+ for (const [key, value] of Object.entries(defaults)) {
187
+ if (!detected[key as keyof TechStack] && value) {
188
+ (detected as Record<string, string>)[key] = value;
189
+ }
190
+ }
191
+
192
+ return detected;
193
+ }
194
+
195
+ // ─── Template Constraints ───────────────────────────────
196
+
197
+ /** Governance constraints added to every generated skill */
198
+ const GOVERNANCE_CONSTRAINTS = [
199
+ 'must_follow_master_plan',
200
+ 'must_follow_architecture',
201
+ 'conflicts_require_change_request',
202
+ ];
203
+
204
+ /** Tech-stack-specific constraints per role */
205
+ const TECH_CONSTRAINTS: Record<string, (ts: TechStack) => string[]> = {
206
+ BACKEND_PROGRAMMER: (ts) => {
207
+ const c: string[] = [];
208
+ if (ts.backend?.includes('FastAPI')) c.push('fastapi_async_required', 'pydantic_validation');
209
+ if (ts.backend?.includes('Django')) c.push('django_orm_required');
210
+ if (ts.backend?.includes('Express')) c.push('express_middleware_pattern');
211
+ if (ts.testing?.includes('Pytest')) c.push('pytest_testing');
212
+ if (ts.testing?.includes('Vitest') || ts.testing?.includes('Jest')) c.push('unit_test_required');
213
+ return c;
214
+ },
215
+ FRONTEND_PROGRAMMER: (ts) => {
216
+ const c: string[] = [];
217
+ if (ts.frontend?.includes('React')) c.push('react_component_pattern');
218
+ if (ts.frontend?.includes('Next')) c.push('nextjs_app_router');
219
+ if (ts.testing?.includes('Vitest') || ts.testing?.includes('Jest')) c.push('component_testing');
220
+ return c;
221
+ },
222
+ DB_EXPERT: (ts) => {
223
+ const c: string[] = [];
224
+ if (ts.database?.includes('PostgreSQL')) c.push('postgresql_best_practices');
225
+ if (ts.orm?.includes('SQLAlchemy')) c.push('sqlalchemy_migrations');
226
+ if (ts.orm?.includes('Prisma')) c.push('prisma_schema');
227
+ return c;
228
+ },
229
+ WEBSITE_PROGRAMMER: (ts) => {
230
+ const c: string[] = [];
231
+ if (ts.frontend?.includes('Next')) c.push('nextjs_ssg_ssr');
232
+ c.push('seo_required', 'responsive_design');
233
+ return c;
234
+ },
235
+ };
236
+
237
+ /**
238
+ * Get deterministic template constraints for a role based on tech stack.
239
+ *
240
+ * @param role - Pipeline role
241
+ * @param techStack - Inferred tech stack
242
+ * @returns Array of constraint identifiers
243
+ */
244
+ export function getTemplateConstraints(role: PipelineRole, techStack: TechStack): string[] {
245
+ const techFn = TECH_CONSTRAINTS[role];
246
+ const techConstraints = techFn ? techFn(techStack) : [];
247
+ return [...GOVERNANCE_CONSTRAINTS, ...techConstraints];
248
+ }
@@ -0,0 +1,53 @@
1
+ /**
2
+ * Type definitions for project-specific skill and constitution generation.
3
+ */
4
+
5
+ import type { OutputLanguage } from '../../types/project.js';
6
+ import type { PipelineRole, RepoSnapshot } from '../types.js';
7
+
8
+ // ─── Tech Stack ─────────────────────────────────────────
9
+
10
+ export interface TechStack {
11
+ backend?: string;
12
+ frontend?: string;
13
+ database?: string;
14
+ orm?: string;
15
+ testing?: string;
16
+ language?: string;
17
+ }
18
+
19
+ // ─── Skill Generation Context ───────────────────────────
20
+
21
+ export interface SkillGenerationContext {
22
+ language: OutputLanguage;
23
+ expandedSpec: string;
24
+ snapshot: RepoSnapshot;
25
+ userDocs?: string;
26
+ sessionGuidance?: string;
27
+ brandContext?: { logoPath?: string; primaryColor?: string };
28
+ activeRoles: PipelineRole[];
29
+ skillsDir: string;
30
+ projectName: string;
31
+ }
32
+
33
+ // ─── Constitution Context ───────────────────────────────
34
+
35
+ export interface ConstitutionContext {
36
+ language: OutputLanguage;
37
+ projectName: string;
38
+ techStack: TechStack;
39
+ expandedSpec: string;
40
+ sessionGuidance?: string;
41
+ brandContext?: { logoPath?: string; primaryColor?: string };
42
+ skillsDir: string;
43
+ }
44
+
45
+ // ─── Marker File ────────────────────────────────────────
46
+
47
+ export interface SkillsGenerationMarker {
48
+ timestamp: string;
49
+ pipelineVersion: string;
50
+ activeRoles: string[];
51
+ techStack: TechStack;
52
+ aiGenerated: boolean;
53
+ }
@@ -32,6 +32,8 @@ export const ArtifactTypeSchema = z.enum([
32
32
  'resolved_commands',
33
33
  'constitution',
34
34
  'change_request',
35
+ 'additional_context',
36
+ 'skill_generation_log',
35
37
  ]);
36
38
  export type ArtifactType = z.infer<typeof ArtifactTypeSchema>;
37
39
 
@@ -97,6 +97,8 @@ export const PipelineStateSchema = z.object({
97
97
  resolvedCommands: ResolvedCommandsSchema.optional(),
98
98
  /** Tracks which phase failed, for recovery routing */
99
99
  failedPhase: PipelinePhaseSchema.optional(),
100
+ /** Session guidance: user steering, upgrade context, or resume instructions */
101
+ sessionGuidance: z.string().optional(),
100
102
  /** Pending change requests that force re-routing to consensus phases (v1.1) */
101
103
  pendingChangeRequests: z.array(z.object({
102
104
  cr_id: z.string(),
@@ -101,8 +101,8 @@ export interface ConsensusConfig {
101
101
  export const DEFAULT_CONSENSUS_CONFIG: Omit<ConsensusConfig, 'openaiKey' | 'geminiKey' | 'grokKey'> = {
102
102
  threshold: 95,
103
103
  maxIterations: 10,
104
- openaiModel: 'gpt-4o',
105
- geminiModel: 'gemini-2.0-flash',
104
+ openaiModel: 'gpt-4.1',
105
+ geminiModel: 'gemini-2.5-flash',
106
106
  grokModel: DEFAULT_GROK_MODEL,
107
107
  reviewer: 'openai',
108
108
  arbitrator: 'gemini',
@@ -122,7 +122,19 @@ export const AIProviderSchema = z.enum(['openai', 'gemini', 'grok']);
122
122
  /**
123
123
  * Known Gemini models (used for suggestions and display, not strict validation)
124
124
  */
125
- export const KNOWN_GEMINI_MODELS = ['gemini-2.0-flash', 'gemini-1.5-pro', 'gemini-1.5-flash'] as const;
125
+ export const KNOWN_GEMINI_MODELS = [
126
+ 'gemini-2.5-pro', 'gemini-2.5-flash', 'gemini-2.5-flash-lite',
127
+ 'gemini-2.0-flash', 'gemini-2.0-pro',
128
+ 'gemini-1.5-pro', 'gemini-1.5-flash',
129
+ ] as const;
130
+
131
+ /**
132
+ * Known Grok models (used for suggestions and display, not strict validation)
133
+ */
134
+ export const KNOWN_GROK_MODELS = [
135
+ 'grok-4-0709', 'grok-3', 'grok-3-mini',
136
+ 'grok-3-fast', 'grok-3-mini-fast', 'grok-2',
137
+ ] as const;
126
138
 
127
139
  /**
128
140
  * Zod schema for Gemini model - accepts any non-empty string to support new models
@@ -144,7 +156,7 @@ export const ConsensusConfigSchema = z.object({
144
156
  geminiKey: z.string().optional(),
145
157
  grokKey: z.string().optional(),
146
158
  openaiModel: OpenAIModelSchema,
147
- geminiModel: GeminiModelSchema.default('gemini-2.0-flash'),
159
+ geminiModel: GeminiModelSchema.default('gemini-2.5-flash'),
148
160
  grokModel: GrokModelSchema.default(DEFAULT_GROK_MODEL),
149
161
  reviewer: AIProviderSchema.default('openai'),
150
162
  arbitrator: AIProviderSchema.default('gemini'),
@@ -58,6 +58,7 @@ export {
58
58
  DEFAULT_GROK_MODEL,
59
59
  AIProviderSchema,
60
60
  KNOWN_GEMINI_MODELS,
61
+ KNOWN_GROK_MODELS,
61
62
  GeminiModelSchema,
62
63
  GrokModelSchema,
63
64
  type AIProvider,