maestro-flow 0.3.17 → 0.3.18

package/dist/src/tools/spec-loader.js

@@ -5,9 +5,10 @@
  * Reads .workflow/specs/*.md, filters by category via static mapping,
  * returns concatenated content.
  */
-import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { readFileSync, existsSync, readdirSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { parseSpecEntries, formatSpecEntries } from './spec-entry-parser.js';
+import { paths } from '../config/paths.js';
 // ============================================================================
 // Filename → Category mapping (single source of truth)
 // ============================================================================
@@ -24,6 +25,7 @@ const SPECS_DIR = '.workflow/specs';
 export const TEAM_SPECS_DIR = '.workflow/collab/specs';
 /** Layer labels used as section headers when multi-directory scanning is active. */
 const LAYER_LABELS = {
+    global: '# Global Specs',
     baseline: '# Baseline Specs',
     team: '# Team Specs',
     // personal label is dynamic — includes uid
@@ -31,32 +33,67 @@ const LAYER_LABELS = {
 // ============================================================================
 // Public API
 // ============================================================================
+/**
+ * Resolve the directory for a given spec scope.
+ *
+ * | scope      | directory                           |
+ * |------------|-------------------------------------|
+ * | project    | .workflow/specs/                    |
+ * | global     | ~/.maestro/specs/                   |
+ * | team       | .workflow/collab/specs/              |
+ * | personal   | .workflow/collab/specs/{uid}/        |
+ */
+export function resolveSpecDir(projectPath, scope, uid) {
+    switch (scope) {
+        case 'global': return paths.specs;
+        case 'team': return join(projectPath, TEAM_SPECS_DIR);
+        case 'personal': {
+            if (!uid)
+                throw new Error('personal scope requires uid');
+            return join(projectPath, TEAM_SPECS_DIR, uid);
+        }
+        case 'project':
+        default: return join(projectPath, SPECS_DIR);
+    }
+}
 /**
  * Load spec files from one or more directories.
  *
- * When `uid` is provided, scans three directories in order:
+ * Layer scanning order (lowest → highest priority):
+ *   0. ~/.maestro/specs/             (global — when `scope` includes global)
  *   1. .workflow/specs/              (baseline)
- *   2. .workflow/collab/specs/       (team shared)
- *   3. .workflow/collab/specs/{uid}/ (personal)
+ *   2. .workflow/collab/specs/       (team shared — when `uid` is provided)
+ *   3. .workflow/collab/specs/{uid}/ (personal — when `uid` is provided)
  *
  * Content from later layers is appended (never replaces earlier content).
  * Each layer's content is prefixed with a header for clarity.
  *
- * When `uid` is absent, only the baseline directory is scanned — identical
- * to the original single-directory behavior.
+ * @param scope   Controls which extra layers to include beyond baseline.
+ *                - 'project': baseline only (default)
+ *                - 'global': global + baseline
+ *                - 'team': baseline + team shared
+ *                - 'personal': baseline + team shared + personal (requires uid)
+ *                - undefined: same as 'project'; uid alone still triggers team+personal for backward compat
  */
-export function loadSpecs(projectPath, category, uid, keyword) {
+export function loadSpecs(projectPath, category, uid, keyword, scope) {
     // Build ordered list of (directory, label) pairs to scan
-    const layers = buildLayers(projectPath, uid);
+    const layers = buildLayers(projectPath, uid, scope);
+    // Auto-init only baseline and global layers.
+    // Team/personal are per-user — auto-creating them for arbitrary uids is wrong.
+    autoInitSeeds(join(projectPath, SPECS_DIR));
+    if (scope === 'global') {
+        autoInitSeeds(paths.specs);
+    }
     const allSections = [];
     const allMatched = [];
     let totalCount = 0;
+    const multiLayer = layers.length > 1;
     for (const { dir, label } of layers) {
         const { sections, matched } = loadFromDir(dir, category, keyword);
         if (sections.length === 0)
             continue;
-        // Only add layer headers when multi-layer mode is active (uid provided)
-        if (uid) {
+        // Add layer headers when multi-layer mode is active (global or uid)
+        if (multiLayer) {
             allSections.push(`${label}\n\n${sections.join('\n\n---\n\n')}`);
         }
         else {
@@ -73,18 +110,26 @@ export function loadSpecs(projectPath, category, uid, keyword) {
         totalLoaded: totalCount,
     };
 }
-function buildLayers(projectPath, uid) {
-    const baseline = {
+function buildLayers(projectPath, uid, scope) {
+    const layers = [];
+    // Global layer — lowest priority
+    if (scope === 'global') {
+        layers.push({ dir: paths.specs, label: LAYER_LABELS.global });
+    }
+    // Baseline — always included
+    layers.push({
         dir: join(projectPath, SPECS_DIR),
         label: LAYER_LABELS.baseline,
-    };
-    if (!uid)
-        return [baseline];
-    return [
-        baseline,
-        { dir: join(projectPath, TEAM_SPECS_DIR), label: LAYER_LABELS.team },
-        { dir: join(projectPath, TEAM_SPECS_DIR, uid), label: `# Personal Specs (${uid})` },
-    ];
+    });
+    // Team + personal layers
+    // Activated by scope='team'|'personal', or by uid (backward compat)
+    if (scope === 'team' || scope === 'personal' || uid) {
+        layers.push({ dir: join(projectPath, TEAM_SPECS_DIR), label: LAYER_LABELS.team });
+        if (uid) {
+            layers.push({ dir: join(projectPath, TEAM_SPECS_DIR, uid), label: `# Personal Specs (${uid})` });
+        }
+    }
+    return layers;
 }
 /**
  * Load spec files from a single directory. Returns empty arrays if the
@@ -174,4 +219,61 @@ function stripFrontmatter(raw) {
         return raw;
     return trimmed.substring(endIdx + 4).trim();
 }
+// ============================================================================
+// Auto-init seed files
+// ============================================================================
+/** Directories already checked this process — skip re-checking. */
+const autoInitChecked = new Set();
+/** Minimal seed files (filename + header). */
+const AUTO_INIT_SEEDS = [
+    ['coding-conventions.md', '# Coding Conventions\n\n## Entries\n\n'],
+    ['architecture-constraints.md', '# Architecture Constraints\n\n## Entries\n\n'],
+    ['learnings.md', '# Learnings\n\n## Entries\n\n'],
+    ['quality-rules.md', '# Quality Rules\n\n## Entries\n\n'],
+    ['debug-notes.md', '# Debug Notes\n\n## Entries\n\n'],
+    ['test-conventions.md', '# Test Conventions\n\n## Entries\n\n'],
+    ['review-standards.md', '# Review Standards\n\n## Entries\n\n'],
+];
+/**
+ * Auto-create a specs directory with seed files if it does not exist.
+ * Applies to every layer (global, baseline, team, personal).
+ *
+ * For project-local dirs: only runs when `.workflow/` already exists
+ * (i.e. the project is maestro-managed).
+ * For global (`~/.maestro/specs/`): always creates — the home dir exists by definition.
+ *
+ * Synchronous, per-directory dedup, best-effort — never throws.
+ */
+function autoInitSeeds(specsDir) {
+    if (autoInitChecked.has(specsDir))
+        return;
+    autoInitChecked.add(specsDir);
+    if (existsSync(specsDir))
+        return;
+    // For project-local paths, only auto-init when .workflow/ already exists.
+    // Global path (under ~/.maestro/) always qualifies.
+    const isGlobal = specsDir === paths.specs;
+    if (!isGlobal) {
+        // Walk up to check if .workflow/ parent exists
+        // specsDir patterns: <project>/.workflow/specs, <project>/.workflow/collab/specs[/<uid>]
+        const workflowIdx = specsDir.replace(/\\/g, '/').indexOf('.workflow/');
+        if (workflowIdx !== -1) {
+            const workflowDir = specsDir.substring(0, workflowIdx + '.workflow'.length);
+            if (!existsSync(workflowDir))
+                return;
+        }
+    }
+    try {
+        mkdirSync(specsDir, { recursive: true });
+        for (const [filename, content] of AUTO_INIT_SEEDS) {
+            const filePath = join(specsDir, filename);
+            if (!existsSync(filePath)) {
+                writeFileSync(filePath, content, 'utf-8');
+            }
+        }
+    }
+    catch {
+        // Best-effort — don't block loading
+    }
+}
 //# sourceMappingURL=spec-loader.js.map

package/dist/src/tools/spec-loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"spec-loader.js","sourceRoot":"","sources":["../../../src/tools/spec-loader.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"spec-loader.js","sourceRoot":"","sources":["../../../src/tools/spec-loader.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-flow",
-  "version": "0.3.17",
+  "version": "0.3.18",
   "description": "Workflow orchestration CLI with MCP endpoint support and extensible architecture",
   "type": "module",
   "imports": {

package/workflows/specs-add.md

@@ -5,45 +5,70 @@ Add a `<spec-entry>` closed-tag entry to a single target spec file by category.
 ## Arguments
 
 ```
-$ARGUMENTS: "<category> <content>"
+$ARGUMENTS: "[--scope <scope>] [--uid <uid>] <category> <content>"
 
+--scope  -- target scope: project (default) | global | team | personal
+--uid    -- user id for personal scope (auto-detected from git if omitted)
 category -- one of: coding, arch, quality, debug, test, review, learning
 content  -- free-text description of the entry
 ```
 
-## Category-to-File Mapping (1:1)
+## Scope-to-Directory Mapping
+
+| Scope | Target directory | uid needed |
+|-------|-----------------|------------|
+| `project` (default) | `.workflow/specs/` | no |
+| `global` | `~/.maestro/specs/` | no |
+| `team` | `.workflow/collab/specs/` | no |
+| `personal` | `.workflow/collab/specs/{uid}/` | yes (auto or `--uid`) |
+
+## Category-to-File Mapping (1:1, same filename in every scope)
 
 | Category | Target file |
 |----------|------------|
-| `coding` | `.workflow/specs/coding-conventions.md` |
-| `arch` | `.workflow/specs/architecture-constraints.md` |
-| `quality` | `.workflow/specs/quality-rules.md` |
-| `debug` | `.workflow/specs/debug-notes.md` |
-| `test` | `.workflow/specs/test-conventions.md` |
-| `review` | `.workflow/specs/review-standards.md` |
-| `learning` | `.workflow/specs/learnings.md` |
+| `coding` | `coding-conventions.md` |
+| `arch` | `architecture-constraints.md` |
+| `quality` | `quality-rules.md` |
+| `debug` | `debug-notes.md` |
+| `test` | `test-conventions.md` |
+| `review` | `review-standards.md` |
+| `learning` | `learnings.md` |
 
 ## Prerequisites
 
-- `.workflow/specs/` directory must exist (run `/spec-setup` first if missing)
+- Target specs directory must exist:
+  - `project`: `.workflow/specs/` (run `/spec-setup` or `maestro spec init`)
+  - `global`: `~/.maestro/specs/` (run `maestro spec init --scope global`)
+  - `team`: `.workflow/collab/specs/` (run `maestro spec init --scope team`)
+  - `personal`: `.workflow/collab/specs/{uid}/` (run `maestro spec init --scope personal`)
 
 ## Execution Steps
 
 ### Step 1: Parse Arguments
 
 ```
-Parse: category = first word, content = remaining text
-Validate: category ∈ {coding, arch, quality, debug, test, review, learning}, content non-empty
-On failure: show usage `/spec-add <category> <content>` with valid categories, exit
+Parse $ARGUMENTS:
+  1. Extract --scope <value> (default: project)
+  2. Extract --uid <value> if present
+  3. category = first remaining word
+  4. content = remaining text
+Validate:
+  - scope ∈ {project, global, team, personal}
+  - category ∈ {coding, arch, quality, debug, test, review, learning}
+  - content non-empty
+  - personal scope requires uid (resolve from `maestro collab whoami` if --uid not given)
+On failure: show usage `/spec-add [--scope <scope>] <category> <content>`, exit
 ```
 
 ### Step 2: Resolve Target File
 
-Map category to file path. If file does not exist, create it with a basic header.
+Resolve directory from scope (see table above), then append `<target_file>` from category mapping.
+
+If file does not exist, create it with a basic header.
 
 Check for near-duplicate entries:
 ```bash
-grep -i "<content_first_10_words>" .workflow/specs/<target_file> | tail -5
+grep -i "<content_first_10_words>" <resolved_dir>/<target_file> | tail -5
 ```
 
 ### Step 3: Extract Keywords
@@ -70,7 +95,10 @@ Read target file. Append the formatted `<spec-entry>` block at the end. Write fi
 
 ### Step 6: Confirm
 
-Display: category, target file, keywords, and verify command (`/spec-load --keyword <kw1>`).
+Display: category, scope, target file path, keywords, and verify command:
+```
+maestro spec load --scope <scope> --keyword <kw1>
+```
 
 ## Output
 

package/workflows/specs-load.md

@@ -1,20 +1,22 @@
 # Workflow: specs-load
 
-Load spec files from `.workflow/specs/`, filtered by category.
+Load spec files filtered by category. Supports project, global, team, and personal scopes.
 
 ## Arguments
 
 ```
-$ARGUMENTS: "[--category <type>] [keyword]"
+$ARGUMENTS: "[--scope <scope>] [--uid <uid>] [--category <type>] [keyword]"
 
+--scope     -- load scope: project (default) | global | team | personal
+--uid       -- user id for personal scope (auto-detected from git if omitted)
 --category  -- filter by category (1:1 mapping to file):
                coding | arch | quality | debug | test | review | learning | all
 keyword     -- optional, grep within loaded specs for matching sections
 ```
 
-## Category → File Mapping (1:1)
+## Category -> File Mapping (1:1)
 
-Each category loads exactly one file. Same mapping as spec-add.
+Each category loads exactly one file per layer. Same mapping as spec-add.
 
 | Category | File loaded |
 |----------|------------|
@@ -27,22 +29,30 @@ Each category loads exactly one file. Same mapping as spec-add.
 | `learning` | `learnings.md` |
 | `all` (default) | All `.md` files in specs/ |
 
+## Layer Order by Scope
+
+| Scope | Layers loaded (lowest -> highest priority) |
+|-------|-------------------------------------------|
+| `project` | baseline only |
+| `global` | global + baseline |
+| `team` | baseline + team shared |
+| `personal` | baseline + team shared + personal (requires uid) |
+
+Each layer is prefixed with a section header when multi-layer.
+
 ## Execution Steps
 
 ### Step 1: Parse Arguments
 
-Extract `--category <type>` (filter) and remaining text (keyword for grep).
+Extract `--scope`, `--uid`, `--category <type>` and remaining text (keyword for grep).
 
 ### Step 2: Load Specs via CLI
 
 ```bash
-maestro spec load --category <category>
+maestro spec load --scope <scope> [--uid <uid>] [--category <category>] [--keyword <word>]
 ```
 
-If `maestro spec load` CLI is unavailable, read files directly:
-```bash
-cat .workflow/specs/<matched-file>
-```
+If `maestro spec load` CLI is unavailable, read files directly from the resolved directory.
 
 ### Step 3: Keyword Filter (optional)
 
@@ -55,5 +65,5 @@ grep -n -i -C 3 "$KEYWORD" <loaded content>
 
 Output loaded specs content. If no specs found, show:
 ```
-(No specs found. Run "maestro spec init" or "/spec-setup" to initialize.)
+(No specs found. Run "maestro spec init --scope <scope>" to initialize.)
 ```