maestro-flow 0.3.10 → 0.3.12

package/workflows/specs-add.md

@@ -1,34 +1,31 @@
 # Workflow: specs-add
 
-Add a timestamped entry to the appropriate system specs file.
+Add a `<spec-entry>` closed-tag entry to a single target spec file by category.
 
 ## Arguments
 
 ```
-$ARGUMENTS: "<type> <content>"
+$ARGUMENTS: "<category> <content>"
 
-type    -- one of: bug, pattern, decision, rule
-content -- free-text description of the entry
+category -- one of: coding, arch, quality, debug, test, review, learning
+content  -- free-text description of the entry
 ```
 
-## Type-to-File Mapping
+## Category-to-File Mapping (1:1)
 
-All entries are first appended to `learnings.md` (primary). Types with secondary targets also update the relevant spec file:
-
-| Type | Primary file | Secondary file |
-|------|-------------|----------------|
-| `bug` | `.workflow/specs/learnings.md` | -- |
-| `pattern` | `.workflow/specs/learnings.md` | `.workflow/specs/coding-conventions.md` |
-| `decision` | `.workflow/specs/learnings.md` | `.workflow/specs/architecture-constraints.md` |
-| `rule` | `.workflow/specs/learnings.md` | `.workflow/specs/quality-rules.md` |
-| `debug` | `.workflow/specs/learnings.md` | `.workflow/specs/debug-notes.md` |
-| `test` | `.workflow/specs/learnings.md` | `.workflow/specs/test-conventions.md` |
-| `review` | `.workflow/specs/learnings.md` | `.workflow/specs/review-standards.md` |
-| `validation` | `.workflow/specs/learnings.md` | `.workflow/specs/validation-rules.md` |
+| 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` |
 
 ## Prerequisites
 
-- `.workflow/specs/` directory must exist (run `/workflow:specs-setup` first if missing)
+- `.workflow/specs/` directory must exist (run `/spec-setup` first if missing)
 
 ## Execution Steps
 
@@ -36,97 +33,65 @@ All entries are first appended to `learnings.md` (primary). Types with secondary
 
 ```
 Split $ARGUMENTS into:
-  type    = first word
-  content = remaining text
+  category = first word
+  content  = remaining text
 
 Validate:
-  - type must be one of: bug, pattern, decision, rule, debug, test, review, validation
+  - category must be one of: coding, arch, quality, debug, test, review, learning
   - content must not be empty
 
 On validation failure:
-  - Display usage: `/workflow:specs-add <type> <content>`
-  - List valid types with descriptions:
-    bug        -- Bug or gotcha learned during development
-    pattern    -- Coding pattern or convention to follow
-    decision   -- Architecture decision or constraint
-    rule       -- Quality rule or enforcement criterion
-    debug      -- Debug tip, root cause record, or known issue workaround
-    test       -- Test convention, pattern, or framework-specific note
-    review     -- Review standard, checklist item, or quality gate
-    validation -- Verification criterion or acceptance standard
+  - Display usage: `/spec-add <category> <content>`
+  - List valid categories
   - Exit
 ```
 
-### Step 2: Resolve Target Files
-
-```
-Map type to file paths using the Type-to-File Mapping table above.
-Verify the primary file (learnings.md) exists.
+### Step 2: Resolve Target File
 
-If file does not exist:
-  - Warn: "Specs not initialized. Run /workflow:specs-setup first."
-  - Exit
-```
+Map category to file path. If file does not exist, create it with a basic header.
 
-Check for near-duplicate entries (same title in last 10 entries of learnings.md):
+Check for near-duplicate entries:
 ```bash
-grep -i "<content_first_10_words>" .workflow/specs/learnings.md | tail -5
+grep -i "<content_first_10_words>" .workflow/specs/<target_file> | tail -5
 ```
 
-If near-duplicate found: warn user and ask to proceed or skip.
-
-### Step 3: Format Entry
+### Step 3: Extract Keywords
 
-```
-Generate timestamp: YYYY-MM-DD HH:mm (local time)
-Generate title by extracting first meaningful phrase from content.
-Auto-extract keywords from content for frontmatter update (see Step 5.5).
+Auto-extract 3-5 relevant keywords from the content:
+- Domain-specific terms (not generic words like "code", "file", "function")
+- Lowercase, no spaces (use hyphens for multi-word terms)
+- Terms that would help future keyword-based lookup
 
-Entry format for learnings.md:
-  ### [YYYY-MM-DD] <type>: <title>
+### Step 4: Format Entry
 
-  <full_content>
 ```
+Generate timestamp: YYYY-MM-DD (local date)
+Generate title from first meaningful phrase of content.
 
-### Step 4: Append to Learnings (Primary)
-
-```
-Read .workflow/specs/learnings.md.
-Find the "## Entries" section.
-Append the formatted entry after the last existing entry (or after the section header if empty).
-Write the file back.
-```
+Entry format (closed-tag):
+<spec-entry category="{category}" keywords="{kw1},{kw2},{kw3}" date="{YYYY-MM-DD}">
 
-### Step 5: Update Secondary Spec File
+### {title}
 
-If the entry type has a secondary target file, update it:
+{content}
 
-| Type | Target file | Update action |
-|------|------------|---------------|
-| `pattern` | `coding-conventions.md` | Add or update convention section |
-| `decision` | `architecture-constraints.md` | Add decision record |
-| `rule` | `quality-rules.md` | Add rule under `## Manual` section |
-| `debug` | `debug-notes.md` | Add entry under `## Entries` section |
-| `test` | `test-conventions.md` | Add entry under `## Manual Additions` section |
-| `review` | `review-standards.md` | Add entry under `## Manual Additions` section |
-| `validation` | `validation-rules.md` | Add entry under `## Manual Additions` section |
-| `bug` | -- | No secondary update (learnings only) |
+</spec-entry>
+```
 
-For pattern/decision/rule: read the target file, find the appropriate section, append the new entry in the file's existing format.
+### Step 5: Append to Target File
 
+Read target file. Append the formatted `<spec-entry>` block at the end. Write file back.
 
 ### Step 6: Confirm
 
 ```
-Display:
-  == specs-add complete ==
-  Type: <category>
-  Added to: .workflow/specs/learnings.md
-  Updated:  .workflow/specs/<secondary_file> (if applicable)
-
-  Entry: ### [date] <type>: <title>
+== spec-add complete ==
+Category: <category>
+Added to: .workflow/specs/<target_file>
+Keywords: <kw1>, <kw2>, <kw3>
+Verify: /spec-load --keyword <kw1>
 ```
 
 ## Output
 
-Entry appended to learnings.md, plus secondary spec file updated if applicable.
+One `<spec-entry>` block appended to the target file.

package/workflows/specs-load.md

@@ -7,27 +7,25 @@ Load spec files from `.workflow/specs/`, filtered by category.
 ```
 $ARGUMENTS: "[--category <type>] [keyword]"
 
---category  -- filter by category:
-               general | planning | execution | debug | test | review | validation
+--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 → Files Mapping
+## Category → File Mapping (1:1)
 
-Categories are resolved by **filename** (no frontmatter required):
+Each category loads exactly one file. Same mapping as spec-add.
 
-| Category | Files loaded |
-|----------|-------------|
-| `execution` | `coding-conventions.md`, `architecture-constraints.md`, `quality-rules.md`, `learnings.md` |
-| `planning` | `architecture-constraints.md`, `learnings.md` |
-| `validation` | `validation-rules.md`, `learnings.md` |
-| `test` | `test-conventions.md`, `learnings.md` |
-| `review` | `review-standards.md`, `learnings.md` |
-| `debug` | `debug-notes.md`, `learnings.md` |
-| `general` | `learnings.md` + any unknown files |
-| _(no filter)_ | All `.md` files in specs/ |
-
-`learnings.md` is always included regardless of category filter.
+| Category | File loaded |
+|----------|------------|
+| `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` |
+| `all` (default) | All `.md` files in specs/ |
 
 ## Execution Steps
 
@@ -47,7 +45,7 @@ maestro spec load --category <category>
 
 If `maestro spec load` CLI is unavailable, read files directly:
 ```bash
-cat .workflow/specs/<matched-files>
+cat .workflow/specs/<matched-file>
 ```
 
 ### Step 3: Keyword Filter (optional)

package/workflows/specs-setup.md

@@ -4,8 +4,8 @@ System specs initialization -- scan project structure, detect tech stack, genera
 
 ## Trigger
 
-- First `/workflow:init` (automatic)
-- Manual `/workflow:specs-setup`
+- First `/maestro-init` (automatic)
+- Manual `/spec-setup`
 
 ## Prerequisites
 
@@ -36,7 +36,7 @@ Detection targets:
   Cargo.toml          --> Rust
   pom.xml             --> Java (Maven)
   build.gradle        --> Java/Kotlin (Gradle)
-  composer.json       --> PHP
+  composer.json        --> PHP
   Gemfile             --> Ruby
   .csproj / .sln      --> .NET/C#
   Dockerfile          --> Container deployment
@@ -85,22 +85,16 @@ Formatting:   Check for .prettierrc, .editorconfig, eslint config
 File naming:  kebab-case vs camelCase vs PascalCase for source files
 ```
 
-### Step 5: Generate coding-conventions.md
+### Step 5: Generate Core Files (always created)
+
+#### 5a: coding-conventions.md
 
 Output: `.workflow/specs/coding-conventions.md`
 
 ```markdown
 ---
 title: "Coding Conventions"
-readMode: required
-priority: high
-category: execution
-keywords:
-  - style
-  - naming
-  - import
-  - pattern
-  - convention
+category: coding
 ---
 # Coding Conventions
 
@@ -126,26 +120,18 @@ Auto-generated from project analysis. Update manually as patterns evolve.
 ## Patterns
 {list detected patterns from codebase analysis}
 
-## Manual Additions
-{empty section for user entries}
+## Entries
+{empty section for spec-add entries}
 ```
 
-### Step 6: Generate architecture-constraints.md
+#### 5b: architecture-constraints.md
 
 Output: `.workflow/specs/architecture-constraints.md`
 
 ```markdown
 ---
 title: "Architecture Constraints"
-readMode: required
-priority: high
-category: planning
-keywords:
-  - architecture
-  - module
-  - layer
-  - boundary
-  - dependency
+category: arch
 ---
 # Architecture Constraints
 
@@ -166,115 +152,57 @@ Auto-generated from project structure. Update manually as architecture evolves.
 - Module system: {ESM | CommonJS | ...}
 - Strict mode: {yes | no}
 
-## Manual Additions
-{empty section for user entries}
+## Entries
+{empty section for spec-add entries}
 ```
 
-### Step 7: Generate learnings.md
+#### 5c: learnings.md
 
 Output: `.workflow/specs/learnings.md`
 
 ```markdown
 ---
 title: "Learnings"
-readMode: optional
-priority: medium
-category: general
-keywords:
-  - bug
-  - lesson
-  - gotcha
+category: learning
 ---
 # Learnings
 
 Bugs, gotchas, and lessons learned during development.
-Add entries with: `/workflow:specs-add bug <description>`
-
-## Format
-
-Each entry follows: `- [{YYYY-MM-DD HH:mm}] <description>`
+Add entries with: `/spec-add learning <description>`
 
 ## Entries
 
-{empty -- entries added via specs-add}
+{empty -- entries added via spec-add}
 ```
 
-### Step 8: Generate quality-rules.md
+### Step 6: Generate Optional Files (when signals detected)
+
+#### 6a: quality-rules.md (when linter config or CI detected)
 
 Output: `.workflow/specs/quality-rules.md`
 
 ```markdown
 ---
 title: "Quality Rules"
-readMode: required
-priority: medium
-category: execution
-keywords:
-  - quality
-  - rule
-  - enforcement
-  - standard
+category: quality
 ---
 # Quality Rules
 
-Project-specific quality rules and enforcement criteria.
-Add entries with: `/workflow:specs-add rule <description>`
-
-## Format
-
-Each entry follows: `- [{YYYY-MM-DD HH:mm}] <description>`
-
-## Entries
-
-{empty -- entries added via specs-add}
-```
-
-### Step 9: Generate debug-notes.md
-
-Output: `.workflow/specs/debug-notes.md`
-
-```markdown
----
-title: "Debug Notes"
-readMode: optional
-priority: medium
-category: debug
-keywords:
-  - debug
-  - issue
-  - workaround
-  - root-cause
-  - gotcha
----
-# Debug Notes
-
-Known issues, debugging tips, and root cause records.
-Add entries with: `/spec-add debug <description>`
-
 ## Entries
 
 {empty -- entries added via spec-add}
 ```
 
-### Step 10: Generate test-conventions.md
-
-Output: `.workflow/specs/test-conventions.md`
+#### 6b: test-conventions.md (when test framework or test files detected)
 
 Scan existing test files for conventions (framework, naming, directory structure, patterns).
 
+Output: `.workflow/specs/test-conventions.md`
+
 ```markdown
 ---
 title: "Test Conventions"
-readMode: required
-priority: high
 category: test
-keywords:
-  - test
-  - coverage
-  - mock
-  - fixture
-  - assertion
-  - framework
 ---
 # Test Conventions
 
@@ -291,80 +219,31 @@ Auto-generated from project analysis. Update manually as patterns evolve.
 - Test files: {detected: *.test.ts | *.spec.ts | test_*.py | etc.}
 
 ## Patterns
-{detected patterns from existing test files: describe/it nesting, assertion style, mock patterns}
-
-## Manual Additions
-
-```
-
-### Step 11: Generate review-standards.md
-
-Output: `.workflow/specs/review-standards.md`
-
-```markdown
----
-title: "Review Standards"
-readMode: required
-priority: medium
-category: review
-keywords:
-  - review
-  - checklist
-  - gate
-  - approval
-  - standard
----
-# Review Standards
-
-## Review Checklist
-
-## Quality Gates
-
-## Manual Additions
+{detected patterns from existing test files}
 
+## Entries
+{empty section for spec-add entries}
 ```
 
-### Step 12: Generate validation-rules.md
-
-Output: `.workflow/specs/validation-rules.md`
+#### 6c: debug-notes.md and review-standards.md
 
-```markdown
----
-title: "Validation Rules"
-readMode: required
-priority: high
-category: validation
-keywords:
-  - validation
-  - verification
-  - acceptance
-  - criteria
-  - check
----
-# Validation Rules
-
-## Verification Criteria
-
-## Acceptance Standards
-
-## Manual Additions
-
-```
+These are NOT created during setup. They are created on demand when `spec-add debug` or `spec-add review` is first used.
 
-### Step 13: Summary
+### Step 7: Summary
 
 Display what was created:
 ```
 Specs initialized:
-  .workflow/project-tech.json        -- Tech stack analysis
-  .workflow/specs/coding-conventions.md    (category: execution)
-  .workflow/specs/architecture-constraints.md (category: planning)
-  .workflow/specs/learnings.md             (category: general)
-  .workflow/specs/quality-rules.md         (category: execution)
-  .workflow/specs/debug-notes.md           (category: debug)
-  .workflow/specs/test-conventions.md      (category: test)
-  .workflow/specs/review-standards.md      (category: review)
-  .workflow/specs/validation-rules.md      (category: validation)
+  .workflow/project-tech.json                    -- Tech stack analysis
+  .workflow/specs/coding-conventions.md          (category: coding)
+  .workflow/specs/architecture-constraints.md    (category: arch)
+  .workflow/specs/learnings.md                   (category: learning)
+  {if created:}
+  .workflow/specs/quality-rules.md               (category: quality)
+  .workflow/specs/test-conventions.md            (category: test)
+
+Categories: coding, arch, quality, debug, test, review, learning
+  debug-notes.md and review-standards.md created on demand via /spec-add
 ```
 
 ## Output

package/workflows/test.md

@@ -22,7 +22,16 @@ Determine test target from $ARGUMENTS:
 
 **If phase number provided** (e.g., "3"):
 - Set `$TARGET_TYPE = "phase"`
-- Set `$PHASE_DIR = ".workflow/phases/{NN}-{slug}/"`
+- Resolve phase dir:
+  ```
+  Read .workflow/state.json → state
+  artifacts = state.artifacts ?? []
+  IF artifacts.length > 0:
+    art = artifacts.find(a => a.type === 'execute' && a.phase === phaseNum)
+    PHASE_DIR = ".workflow/" + art.path
+  ELSE:
+    PHASE_DIR = ".workflow/phases/{NN}-{slug}/"
+  ```
 - Load `$PHASE_DIR/index.json` for context
 
 **If scratch task ID provided:**
@@ -45,8 +54,9 @@ Validate target exists and has been verified (verification.json present). (E002)
 ### Step 2: Check Active Sessions
 
 ```bash
-find .workflow/phases -name "uat.md" -type f 2>/dev/null | head -5
+# Check both scratch (artifact registry) and legacy phases for active UAT sessions
 find .workflow/scratch -name "uat.md" -type f 2>/dev/null | head -5
+find .workflow/phases -name "uat.md" -type f 2>/dev/null | head -5
 ```
 
 Read each file's frontmatter (status, target) and Current Test section.

package/workflows/ui-style.md

@@ -21,8 +21,15 @@ Pipeline position: analyze -> **ui-design** -> plan -> execute -> verify
 Input: <phase> argument (number or slug) OR topic text
 
 IF argument is a number or matches phase pattern:
-  1. Find .workflow/phases/{NN}-*/index.json
-  2. Set PHASE_DIR = resolved path, SCRATCH_MODE = false
+  Read .workflow/state.json → state
+  artifacts = state.artifacts ?? []
+  IF artifacts.length > 0:
+    art = artifacts.find(a => a.phase === phaseNum)
+    PHASE_DIR = ".workflow/" + art.path
+  ELSE:
+    Find .workflow/phases/{NN}-*/index.json
+    PHASE_DIR = resolved path
+  Set SCRATCH_MODE = false
 
 ELSE (topic text — scratch mode):
   1. slug = slugify(topic)