maestro-flow 0.1.0

package/workflows/specs-add.md

@@ -0,0 +1,132 @@
+# Workflow: specs-add
+
+Add a timestamped entry to the appropriate system specs file.
+
+## Arguments
+
+```
+$ARGUMENTS: "<type> <content>"
+
+type    -- one of: bug, pattern, decision, rule
+content -- free-text description of the entry
+```
+
+## Type-to-File Mapping
+
+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` |
+
+## Prerequisites
+
+- `.workflow/specs/` directory must exist (run `/workflow:specs-setup` first if missing)
+
+## Execution Steps
+
+### Step 1: Parse Arguments
+
+```
+Split $ARGUMENTS into:
+  type    = first word
+  content = remaining text
+
+Validate:
+  - type must be one of: bug, pattern, decision, rule, debug, test, review, validation
+  - 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
+  - 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.
+
+If file does not exist:
+  - Warn: "Specs not initialized. Run /workflow:specs-setup first."
+  - Exit
+```
+
+Check for near-duplicate entries (same title in last 10 entries of learnings.md):
+```bash
+grep -i "<content_first_10_words>" .workflow/specs/learnings.md | tail -5
+```
+
+If near-duplicate found: warn user and ask to proceed or skip.
+
+### Step 3: Format Entry
+
+```
+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).
+
+Entry format for learnings.md:
+  ### [YYYY-MM-DD] <type>: <title>
+
+  <full_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.
+```
+
+### Step 5: Update Secondary Spec File
+
+If the entry type has a secondary target file, update it:
+
+| 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) |
+
+For pattern/decision/rule: read the target file, find the appropriate section, append the new entry in the file's existing format.
+
+
+### 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>
+```
+
+## Output
+
+Entry appended to learnings.md, plus secondary spec file updated if applicable.

package/workflows/specs-load.md

@@ -0,0 +1,65 @@
+# Workflow: specs-load
+
+Load spec files from `.workflow/specs/`, filtered by category.
+
+## Arguments
+
+```
+$ARGUMENTS: "[--category <type>] [keyword]"
+
+--category  -- filter by category:
+               general | planning | execution | debug | test | review | validation
+keyword     -- optional, grep within loaded specs for matching sections
+```
+
+## Category → Files Mapping
+
+Categories are resolved by **filename** (no frontmatter required):
+
+| 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.
+
+## Execution Steps
+
+### Step 1: Parse Arguments
+
+```
+Parse $ARGUMENTS:
+  --category <type>  -> category filter
+  remaining text     -> keyword for grep filtering
+```
+
+### Step 2: Load Specs via CLI
+
+```bash
+maestro spec load --category <category>
+```
+
+If `maestro spec load` CLI is unavailable, read files directly:
+```bash
+cat .workflow/specs/<matched-files>
+```
+
+### Step 3: Keyword Filter (optional)
+
+If keyword provided, grep within loaded content:
+```bash
+grep -n -i -C 3 "$KEYWORD" <loaded content>
+```
+
+### Step 4: Display Results
+
+Output loaded specs content. If no specs found, show:
+```
+(No specs found. Run "maestro spec init" or "/spec-setup" to initialize.)
+```

package/workflows/specs-setup.md

@@ -0,0 +1,372 @@
+# Workflow: specs-setup
+
+System specs initialization -- scan project structure, detect tech stack, generate convention files.
+
+## Trigger
+
+- First `/workflow:init` (automatic)
+- Manual `/workflow:specs-setup`
+
+## Prerequisites
+
+- Project root must exist
+- `.workflow/` directory should exist (create if missing)
+
+## Execution Steps
+
+### Step 1: Ensure Directory Structure
+
+```
+Create directories if not present:
+  .workflow/
+  .workflow/specs/
+```
+
+### Step 2: Scan Project Structure
+
+Scan the project root for tech stack indicators:
+
+```
+Detection targets:
+  package.json        --> Node.js ecosystem (read dependencies for framework detection)
+  tsconfig.json       --> TypeScript
+  pyproject.toml      --> Python (modern)
+  requirements.txt    --> Python (legacy)
+  go.mod              --> Go
+  Cargo.toml          --> Rust
+  pom.xml             --> Java (Maven)
+  build.gradle        --> Java/Kotlin (Gradle)
+  composer.json       --> PHP
+  Gemfile             --> Ruby
+  .csproj / .sln      --> .NET/C#
+  Dockerfile          --> Container deployment
+  docker-compose.yml  --> Multi-container orchestration
+
+Framework detection (from dependency files):
+  react / next        --> React / Next.js
+  vue                 --> Vue.js
+  angular             --> Angular
+  express / fastify   --> Node.js server
+  django / flask      --> Python web
+  gin / echo          --> Go web
+  spring              --> Java Spring
+```
+
+### Step 3: Write project-tech.json
+
+Output: `.workflow/project-tech.json`
+
+```json
+{
+  "detected_at": "{ISO timestamp}",
+  "languages": ["TypeScript", "..."],
+  "frameworks": ["Next.js", "..."],
+  "package_manager": "npm | yarn | pnpm | ...",
+  "build_system": "tsc | webpack | vite | ...",
+  "test_framework": "jest | vitest | pytest | ...",
+  "linter": "eslint | prettier | ...",
+  "architecture": {
+    "type": "monorepo | single-package | ...",
+    "entry_points": ["src/index.ts", "..."],
+    "key_directories": ["src/", "lib/", "..."]
+  }
+}
+```
+
+### Step 4: Detect Code Patterns
+
+Scan source files for coding conventions:
+
+```
+Indentation:  Count leading spaces/tabs in first 20 source files
+Naming:       Scan exports for camelCase / PascalCase / snake_case patterns
+Imports:      Check import style (named vs default, path aliases, barrel exports)
+Formatting:   Check for .prettierrc, .editorconfig, eslint config
+File naming:  kebab-case vs camelCase vs PascalCase for source files
+```
+
+### Step 5: Generate 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
+---
+# Coding Conventions
+
+Auto-generated from project analysis. Update manually as patterns evolve.
+
+## Formatting
+- Indentation: {detected}
+- Line length: {detected or "not configured"}
+- Trailing commas: {detected}
+- Semicolons: {detected}
+
+## Naming
+- Variables/functions: {camelCase | snake_case}
+- Classes/types: {PascalCase}
+- Constants: {UPPER_SNAKE_CASE | camelCase}
+- Files: {kebab-case | camelCase | PascalCase}
+
+## Imports
+- Style: {named imports | default imports | mixed}
+- Path aliases: {@ | ~ | none}
+- Order: {built-in, external, internal, relative}
+
+## Patterns
+{list detected patterns from codebase analysis}
+
+## Manual Additions
+{empty section for user entries}
+```
+
+### Step 6: Generate 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
+---
+# Architecture Constraints
+
+Auto-generated from project structure. Update manually as architecture evolves.
+
+## Module Structure
+- Type: {monorepo | single-package | multi-package}
+- Key modules: {list detected top-level directories with purposes}
+
+## Layer Boundaries
+{detected layers: e.g., commands/ -> core/ -> tools/ -> types/}
+
+## Dependency Rules
+{detected from imports: which modules import from which}
+
+## Technology Constraints
+- Runtime: {Node.js >= X | Python >= X | ...}
+- Module system: {ESM | CommonJS | ...}
+- Strict mode: {yes | no}
+
+## Manual Additions
+{empty section for user entries}
+```
+
+### Step 7: Generate learnings.md
+
+Output: `.workflow/specs/learnings.md`
+
+```markdown
+---
+title: "Learnings"
+readMode: optional
+priority: medium
+category: general
+keywords:
+  - bug
+  - lesson
+  - gotcha
+---
+# 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>`
+
+## Entries
+
+{empty -- entries added via specs-add}
+```
+
+### Step 8: Generate quality-rules.md
+
+Output: `.workflow/specs/quality-rules.md`
+
+```markdown
+---
+title: "Quality Rules"
+readMode: required
+priority: medium
+category: execution
+keywords:
+  - quality
+  - rule
+  - enforcement
+  - standard
+---
+# 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`
+
+Scan existing test files for conventions (framework, naming, directory structure, patterns).
+
+```markdown
+---
+title: "Test Conventions"
+readMode: required
+priority: high
+category: test
+keywords:
+  - test
+  - coverage
+  - mock
+  - fixture
+  - assertion
+  - framework
+---
+# Test Conventions
+
+Auto-generated from project analysis. Update manually as patterns evolve.
+
+## Framework
+- Framework: {detected: Jest | Vitest | pytest | Mocha | none}
+- Run command: {detected: npm test | pytest | etc.}
+
+## Directory Structure
+- Pattern: {detected: __tests__/ | tests/ | co-located | etc.}
+
+## Naming Conventions
+- 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
+
+```
+
+### Step 12: Generate validation-rules.md
+
+Output: `.workflow/specs/validation-rules.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
+
+```
+
+### Step 13: 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)
+```
+
+## Output
+
+All files listed above under `.workflow/`.