@sylphx/flow 2.25.0 → 2.27.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @sylphx/flow
 
+## 2.27.0 (2025-12-18)
+
+### ✨ Features
+
+- **flow:** auto-create PRODUCT.md and ARCHITECTURE.md if missing ([3ae7db8](https://github.com/SylphxAI/flow/commit/3ae7db8770920422597ab073ba69b48248fd1f8b))
+
+## 2.26.0 (2025-12-18)
+
+### ✨ Features
+
+- **rules:** add Project Context - PRODUCT.md and ARCHITECTURE.md ([cf7383f](https://github.com/SylphxAI/flow/commit/cf7383f1d8d4176dc605bc01e9ac3da6d3750af4))
+
 ## 2.25.0 (2025-12-18)
 
 ### ✨ Features

package/assets/rules/core.md

@@ -120,6 +120,15 @@ Before accepting any approach:
 
 **These actions are AUTOMATIC. Do without being asked.**
 
+### Project Context
+- **Before significant work**, read:
+  - `PRODUCT.md` — Vision, goals, features, target users, success metrics
+  - `ARCHITECTURE.md` — Tech stack, patterns, decisions, system design
+- **If files don't exist**, create them with appropriate structure for the project
+- **Update immediately** when relevant changes happen
+- Product doc = WHAT and WHY. Architecture doc = HOW.
+- These docs are SSOT. Code is implementation detail.
+
 ### Task Management
 - Complex task (3+ steps) → Write todos immediately, update as you progress
 - Long conversation → Check git log + todos before continuing

package/assets/templates/ARCHITECTURE.md

@@ -0,0 +1,59 @@
+# ARCHITECTURE
+
+## Tech Stack
+
+| Layer | Technology | Why |
+|-------|------------|-----|
+| Frontend | ... | ... |
+| Backend | ... | ... |
+| Database | ... | ... |
+| Auth | ... | ... |
+| Payments | ... | ... |
+| Hosting | ... | ... |
+
+## System Design
+
+High-level architecture overview.
+
+```
+[Diagram or description]
+```
+
+## Key Patterns
+
+What patterns and conventions do we follow?
+
+- **State management**: ...
+- **API design**: ...
+- **Error handling**: ...
+- **Testing**: ...
+
+## Data Models
+
+Core entities and relationships.
+
+## Integrations
+
+External services and APIs.
+
+| Service | Purpose | Notes |
+|---------|---------|-------|
+| ... | ... | ... |
+
+## Technical Decisions
+
+Key decisions and rationale (ADRs).
+
+### Decision: [Title]
+- **Context**: ...
+- **Decision**: ...
+- **Rationale**: ...
+- **Consequences**: ...
+
+## Known Limitations
+
+Technical debt, constraints, areas for improvement.
+
+---
+
+*Last updated: YYYY-MM-DD*

package/assets/templates/PRODUCT.md

@@ -0,0 +1,51 @@
+# PRODUCT
+
+## Vision
+
+What is this product? Why does it exist? What problem does it solve?
+
+## Success Metrics
+
+How do we know we're winning?
+
+- Revenue target?
+- User growth?
+- Engagement?
+- Market position?
+
+## Target Users
+
+Who are we building for? What are their pain points?
+
+## Value Propositions
+
+Why would users choose this over alternatives?
+
+## Key Features
+
+What are the core capabilities?
+
+| Feature | Status | Priority |
+|---------|--------|----------|
+| ... | ... | ... |
+
+## Competitive Landscape
+
+Who are the competitors? What's our differentiation?
+
+## Roadmap
+
+What's next? What's the priority order?
+
+### Now
+- ...
+
+### Next
+- ...
+
+### Later
+- ...
+
+---
+
+*Last updated: YYYY-MM-DD*

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sylphx/flow",
-	"version": "2.25.0",
+	"version": "2.27.0",
 	"description": "One CLI to rule them all. Unified orchestration layer for AI coding assistants. Auto-detection, auto-installation, auto-upgrade.",
 	"type": "module",
 	"bin": {

package/src/core/flow-executor.ts

@@ -5,6 +5,9 @@
  */
 
 import chalk from 'chalk';
+import { existsSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
 import type { Target } from '../types/target.types.js';
 import { AttachManager } from './attach-manager.js';
 import { BackupManager } from './backup-manager.js';
@@ -93,7 +96,8 @@ export class FlowExecutor {
       return { joined: true };
     }
 
-    // First session - stash, backup, attach (all silent)
+    // First session - ensure project docs, stash, backup, attach (all silent)
+    await this.ensureProjectDocs(projectPath);
     await this.gitStashManager.stashSettingsChanges(projectPath);
     const backup = await this.backupManager.createBackup(projectPath, projectHash, target);
 
@@ -259,6 +263,28 @@ export class FlowExecutor {
     }
   }
 
+  /**
+   * Ensure PRODUCT.md and ARCHITECTURE.md exist in project root
+   * Creates from templates if missing
+   */
+  private async ensureProjectDocs(projectPath: string): Promise<void> {
+    const templatesDir = this.templateLoader.getAssetsDir();
+    const templates = [
+      { name: 'PRODUCT.md', template: path.join(templatesDir, 'templates', 'PRODUCT.md') },
+      { name: 'ARCHITECTURE.md', template: path.join(templatesDir, 'templates', 'ARCHITECTURE.md') },
+    ];
+
+    for (const { name, template } of templates) {
+      const targetPath = path.join(projectPath, name);
+
+      // Only create if file doesn't exist and template exists
+      if (!existsSync(targetPath) && existsSync(template)) {
+        const content = await fs.readFile(template, 'utf-8');
+        await fs.writeFile(targetPath, content, 'utf-8');
+      }
+    }
+  }
+
   /**
    * Cleanup after execution (silent)
    */