maestro-flow 0.3.38 → 0.3.39

package/.codex/skills/maestro-ui-design/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: maestro-ui-design
-description: Generate UI design prototypes with multiple styles. User selects style/palette/typography, generates design tokens, produces prototypes. Delegates to ui-ux-pro-max when available, falls back to self-contained pipeline.
-argument-hint: "[topic] [-y] [--style-skill PKG]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion
+description: Generate UI design prototypes, select and solidify as code
+argument-hint: "<phase|topic> [--styles N] [--stack <stack>] [--targets <pages>] [--layouts N] [--refine] [--persist] [--full] [-y] [--style-skill PKG]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, request_user_input
 ---
 
 <purpose>
@@ -13,6 +13,13 @@ Two workflow paths, auto-selected by skill availability:
 Both produce the same output contract for downstream plan/execute consumption.
 </purpose>
 
+<deferred_reading>
+- [ui-style.md](~/.maestro/workflows/ui-style.md) — read when SKILL_PATH found (primary path)
+- [ui-design.md](~/.maestro/workflows/ui-design.md) — read when SKILL_PATH empty or --full (fallback path)
+- [index.json](~/.maestro/templates/index.json) — read when updating phase metadata
+- [scratch-index.json](~/.maestro/templates/scratch-index.json) — read when operating in scratch mode
+</deferred_reading>
+
 <context>
 $ARGUMENTS -- phase number or topic text, plus optional flags.
 
@@ -32,6 +39,8 @@ $maestro-ui-design "3 --style-skill PKG --stack react"
 - `--styles N`: Number of style variants (default: 3, range: 2-5)
 - `--stack <stack>`: Tech stack for implementation guidelines (default: html-tailwind)
 - `--targets <pages>`: Comma-separated page/component targets
+- `--layouts N`: Number of layout templates per target (default: 2, range: 1-4, fallback path only)
+- `--refine`: Iterate on existing design-ref/ — load current tokens, present refinement options
 - `--persist`: Save design system with hierarchical page overrides
 - `--full`: Force full 4-layer self-contained pipeline
 
@@ -65,12 +74,39 @@ Search for `ui-ux-pro-max` script at `skills/ui-ux-pro-max/scripts/search.py` or
 - If `--style-skill PKG` provided: override detected path
 - If `--full`: force self-contained pipeline regardless of skill availability
 
+### Step 2.5: Refine Mode Branch (if `--refine`)
+
+If `--refine` is set:
+1. Verify `design-ref/` exists in target directory (error E004 if missing)
+2. Read current `design-ref/MASTER.md`, `design-tokens.json`, `animation-tokens.json`
+3. Display current design summary (palette, typography, key components)
+4. `request_user_input`:
+   ```json
+   { "questions": [{ "id": "refine_scope", "header": "Refine", "question": "Which aspects to refine?", "options": [
+     { "label": "Colors & Typography (Recommended)", "description": "Adjust palette, font pairings, and scale." },
+     { "label": "Layout & Spacing", "description": "Adjust grid, spacing tokens, and breakpoints." },
+     { "label": "Full Redesign", "description": "Regenerate all variants from scratch, keeping requirements." }
+   ]}] }
+   ```
+5. Apply refinement: directly edit token files and MASTER.md based on user feedback
+6. Update `selection.json` with refinement metadata (iteration count, changes)
+7. Skip to Step 8 (report)
+
 ### Step 3: Gather Requirements Context
 
 1. Read phase context (context.md, brainstorm results, spec references)
 2. Synthesize design brief: product_type, industry, style_keywords, audience
 3. Infer targets from phase goal if not specified (fallback: "home")
-4. **Interactive brief review** (skip if `-y`): present brief, allow user adjustments
+4. **Interactive brief review** (skip if `-y`):
+   - Present synthesized brief (product_type, industry, style_keywords, audience, targets)
+   - `request_user_input`:
+     ```json
+     { "questions": [{ "id": "brief_review", "header": "Brief", "question": "Design brief ready. Proceed with this direction?", "options": [
+       { "label": "Proceed (Recommended)", "description": "Generate variants with current brief." },
+       { "label": "Adjust", "description": "Modify keywords, audience, or targets before generating." }
+     ]}] }
+     ```
+   - **Adjust** → user provides changes, update brief, then proceed
 
 ### Step 4: Generate Style Variants
 
@@ -83,13 +119,33 @@ python3 "${SKILL_PATH}" "${variant_keywords}" --design-system -p "${project_name
 
 **If SKILL_PATH empty or --full (fallback path):**
 
-Spawn ui-design-agent to generate variants using 6D attribute space (mood, density, contrast, rounding, motion, color-temp) for maximum contrast between styles.
+Spawn ui-design-agent to generate variants using 6D attribute space for maximum contrast:
+
+| Dimension | Range | Description |
+|-----------|-------|-------------|
+| mood | formal ↔ playful | Overall emotional tone |
+| density | spacious ↔ dense | Content density and whitespace |
+| contrast | subtle ↔ bold | Visual weight and contrast ratios |
+| rounding | sharp ↔ rounded | Border radius scale (0-24px) |
+| motion | minimal ↔ expressive | Animation intensity and frequency |
+| color-temp | cool ↔ warm | Color temperature bias |
+
+Each variant occupies a distinct region in 6D space — no two variants within 0.3 Euclidean distance.
 
 ### Step 5: Present and Select
 
-Present all variants with key attributes (colors, typography, effects).
+Present all variants with key attributes (colors, typography, effects, 6D coordinates for fallback path).
+
+**Interactive** (default): `request_user_input` with variants as options:
+```json
+{ "questions": [{ "id": "variant_select", "header": "Style", "question": "Select preferred design variant:", "options": [
+  { "label": "Variant 1 (Recommended)", "description": "Brief: palette + mood + key trait." },
+  { "label": "Variant 2", "description": "Brief: palette + mood + key trait." },
+  { "label": "Variant 3", "description": "Brief: palette + mood + key trait." }
+]}] }
+```
+Options built dynamically from generated variants. User may respond with "Other" to request regeneration with different keywords.
 
-**Interactive** (default): user selects variant number, "redo", or "all"
 **Auto** (`-y`): select variant 1
 
 ### Step 6: Solidify Selected Design
@@ -102,14 +158,41 @@ Write output artifacts:
 - `design-ref/animation-tokens.json` -- animation system
 - `design-ref/selection.json` -- selection metadata + rationale
 
-### Step 7: Optional Prototype Generation
+### Step 6.5: Layout Template Generation (fallback path only)
+
+For each target, generate `layoutCount` layout templates:
+- Each template defines `dom_structure` (semantic HTML skeleton) + `css_layout_rules` (grid/flex layout)
+- Write to `design-ref/layout-templates/{target}-layout-{N}.json`
+- Templates vary in content organization: e.g., hero-first vs. feature-grid vs. sidebar-nav
 
-For each target, spawn Agent to generate standalone HTML+CSS prototype from design-tokens.json and animation-tokens.json. Requirements: realistic content (no lorem ipsum), SVG icons via CDN, responsive at 375/768/1024px, WCAG AA contrast.
+### Step 7: Prototype Generation
+
+**Primary path**: For each target, spawn Agent to generate standalone HTML+CSS prototype from design-tokens.json and animation-tokens.json.
+
+**Fallback path**: Assemble prototype matrix: `styles × layouts × targets`. For each combination:
+- Merge selected style tokens + layout template + target content
+- Generate standalone HTML+CSS prototype
+
+Requirements (both paths): realistic content (no lorem ipsum), SVG icons via CDN, responsive at 375/768/1024px, WCAG AA contrast.
+
+**Fallback path only**: Generate `design-ref/compare.html` — interactive matrix viewer showing all prototypes side-by-side with style/layout/target filtering.
 
 ### Step 8: Update State and Report
 
 1. Update index.json with `design_ref` status
-2. Display completion report: phase, variant count + selected, stack, targets, design system artifact paths (`MASTER.md`, `design-tokens.json`, `animation-tokens.json`, `prototypes/`). Suggest next: `$maestro-plan {phase}` or `$maestro-ui-design {phase} --refine`.
+2. Display completion report: phase, variant count + selected, stack, targets, artifact paths
+3. **Next-Step Routing** (skip if `-y` — default to Plan):
+   - `request_user_input`:
+     ```json
+     { "questions": [{ "id": "next_step", "header": "Next Step", "question": "Design system complete. What next?", "options": [
+       { "label": "Plan (Recommended)", "description": "Create execution plan with design reference." },
+       { "label": "Refine", "description": "Iterate on selected design with adjustments." },
+       { "label": "Analyze", "description": "Evaluate feasibility before planning." }
+     ]}] }
+     ```
+     - **Plan** → invoke `maestro-plan {phase}`
+     - **Refine** → invoke `maestro-ui-design {phase} --refine`
+     - **Analyze** → invoke `maestro-analyze {phase}`
 </execution>
 
 <error_codes>
@@ -121,15 +204,29 @@ For each target, spawn Agent to generate standalone HTML+CSS prototype from desi
 | E004 | error | --refine requires existing design-ref/ | Run without --refine first |
 | W001 | warning | Design system returned partial results | Retry with broader keywords |
 | W002 | warning | Prototype rendering failed for one variant | Continue with remaining |
+| W003 | warning | No context.md found, using phase goal only | Continue with phase goal |
 | W004 | warning | ui-ux-pro-max not found, using fallback | Proceed with self-contained pipeline |
 </error_codes>
 
 <success_criteria>
+**Common (both paths)**:
 - [ ] Target resolved (phase or scratch directory)
+- [ ] Requirements context gathered (context.md, brainstorm, or user input)
 - [ ] Style variants generated with intentional contrast
 - [ ] User selected variant (or auto-picked in `-y` mode)
 - [ ] MASTER.md + design-tokens.json + animation-tokens.json + selection.json written
-- [ ] Colors in OKLCH format, WCAG AA contrast met
-- [ ] Prototypes generated for all targets (if applicable)
+- [ ] Colors in OKLCH format, WCAG AA contrast met (4.5:1 text, 3:1 UI)
+- [ ] Prototypes generated for all targets with realistic content (no lorem ipsum)
 - [ ] index.json updated with design_ref status
+- [ ] Next-step routing presented (or auto-defaulted with `-y`)
+
+**Primary path (ui-ux-pro-max)**:
+- [ ] ui-ux-pro-max `--design-system` called with product/industry/style keywords
+- [ ] Tokens extracted from ui-ux-pro-max output into structured JSON
+
+**Fallback path (--full or no skill)**:
+- [ ] 6D attribute space used with ≥0.3 Euclidean distance between variants
+- [ ] Layout templates generated per target (`dom_structure` + `css_layout_rules`)
+- [ ] Prototype matrix assembled: selected style × layouts × targets
+- [ ] `compare.html` generated as interactive matrix viewer
 </success_criteria>

package/.codex/skills/maestro-verify/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: maestro-verify
-description: Goal-Backward 3-layer verification via CSV wave pipeline. Staged parallel waves check Truths, Artifacts, and Wiring with anti-pattern scan and Nyquist test coverage audit. Replaces maestro-verify command.
+description: Verify goals with must-have checks and test coverage validation
 argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"<phase> [--skip-tests] [--skip-antipattern]\""
-allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
 <purpose>
@@ -56,6 +56,7 @@ Wave-based 3-layer Goal-Backward verification using `spawn_agents_on_csv`. Decom
 |                                                                         |
 +-------------------------------------------------------------------------+
 ```
+
 </purpose>
 
 <context>
@@ -175,6 +176,14 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column.
 
 Create session directory.
 
+### Pre-flight: Team Conflict Check
+
+Before starting verification, run:
+```
+Bash("maestro collab preflight --phase <phase-number>")
+```
+If exit code is 1, present warnings and ask whether to proceed.
+
 ### Phase 1: Phase Resolution -> CSV
 
 **Objective**: Resolve phase, load artifacts, establish must-haves, decompose into check tasks, generate tasks.csv.
@@ -188,6 +197,8 @@ Create session directory.
    - All `.task/TASK-{NNN}.json` -- task definitions with convergence.criteria
    - All `.summaries/TASK-{NNN}-summary.md` -- execution results
    - `uat.md` (if exists) -- human UAT gaps to incorporate
+   - `.workflow/codebase/ARCHITECTURE.md` (if exists) -- module wiring expectations for Layer 3 checks
+   - `maestro wiki search "architecture constraint" --json 2>/dev/null` -- documented invariants as additional truth checks (if available)
 
 3. **Must-have establishment** (priority order):
    - **success_criteria from index.json** -- primary contract
@@ -233,7 +244,7 @@ Filter `wave == 1 && status == pending` from master CSV. No prev_context (no pre
 spawn_agents_on_csv({
   csv_path: `${sessionFolder}/wave-1.csv`,
   id_column: "id",
-  instruction: buildVerifyInstruction(sessionFolder, "wave1"),
+  instruction: buildVerifyInstruction(sessionFolder, "wave1"),  // agent: ~/.codex/agents/workflow-verifier.toml
   max_concurrency: maxConcurrency,
   max_runtime_seconds: 3600,
   output_csv_path: `${sessionFolder}/wave-1-results.csv`,
@@ -383,13 +394,20 @@ Issue Refs: {issue_ids}
 
 15. **Post-verify Knowledge Inquiry** (before next step routing):
 
-| Signal | Prompt User | Spec Category |
-|--------|-------------|---------------|
-| Anti-pattern blockers found | "Update `quality-rules.md`?" | `quality` via `/spec-add` |
-| Constraint/wiring violations | "Update `architecture-constraints.md`?" | `arch` via `/spec-add` |
-| Recurring Nyquist coverage gaps | "Add to `test-conventions.md`?" | `test` via `/spec-add` |
+| Signal | Prompt User | Spec Category | Target File |
+|--------|-------------|---------------|-------------|
+| Anti-pattern blockers found | "Verification found {N} anti-patterns. Update quality rules?" | `quality` | `quality-rules.md` |
+| Constraint/wiring violations | "Architecture constraint violations found. Update constraints?" | `arch` | `architecture-constraints.md` |
+| Recurring Nyquist coverage gaps | "Persistent test gap in {module}. Add to test conventions?" | `test` | `test-conventions.md` |
+| Stub/placeholder detected | "Stub artifacts found. Record as quality anti-pattern?" | `quality` | `quality-rules.md` |
+| Missing wiring (orphaned modules) | "Orphaned modules detected. Document wiring requirement?" | `arch` | `architecture-constraints.md` |
+
+On user confirm, invoke `maestro spec add <category> "<title>" "<content>" --keywords ... --source verify:{sessionId}`.
 
-On user confirm, append `<spec-entry>` to matching category file.
+Use `request_user_input` for prompts:
+```json
+{ "questions": [{ "id": "knowledge-capture", "header": "Post-Verify Knowledge Capture", "question": "...", "options": [{ "label": "Yes", "description": "Record to specs" }, { "label": "Skip", "description": "Continue without recording" }] }] }
+```
 
 16. **Next step routing**:
 

package/.codex/skills/manage-codebase-rebuild/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: manage-codebase-rebuild
-description: Full codebase documentation rebuild via CSV wave pipeline. Spawns 5 parallel doc generator agents to scan project and produce complete .workflow/codebase/ documentation set. Replaces manage-codebase-rebuild command.
+description: Rebuild all codebase documentation from scratch
 argument-hint: "[-y|--yes] [-c|--concurrency 5] [--continue] \"[--force] [--skip-commit]\""
 allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 ---
@@ -44,6 +44,7 @@ Single-wave parallel execution -- 5 independent doc generator agents each analyz
 |                                                                           |
 +---------------------------------------------------------------------------+
 ```
+
 </purpose>
 
 <context>
@@ -198,7 +199,7 @@ Filter master `tasks.csv` for `wave == 1 AND status == pending` → write `wave-
 spawn_agents_on_csv({
   csv_path: `${sessionFolder}/wave-1.csv`,
   id_column: "id",
-  instruction: buildRebuildInstruction(sessionFolder, sourceDirs),
+  instruction: buildRebuildInstruction(sessionFolder, sourceDirs),  // agent: ~/.codex/agents/workflow-codebase-mapper.toml
   max_concurrency: maxConcurrency,
   max_runtime_seconds: 3600,
   output_csv_path: `${sessionFolder}/wave-1-results.csv`,

package/.codex/skills/manage-codebase-refresh/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: manage-codebase-refresh
-description: Incremental refresh of codebase docs based on recent git changes
+description: Refresh codebase docs from recent changes
 argument-hint: "[--since <date>] [--deep]"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 ---

package/.codex/skills/manage-harvest/SKILL.md

@@ -1,91 +1,91 @@
----
-name: manage-harvest
-description: Extract knowledge fragments from workflow artifacts (analysis, brainstorm, debug, lite-plan, scratchpad, sessions) and route to wiki / spec / issue stores. Dedup via stable fragment IDs. Closed-loop with downstream consumers.
-argument-hint: "[<session-id|path>] [--to wiki|spec|issue|auto] [--source <type>] [--recent N] [--dry-run] [-y]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
-
-<purpose>
-Knowledge extraction from workflow artifacts, routed into three stores: wiki entries,
-spec conventions, and trackable issues. Prevents knowledge loss from completed sessions.
-
-**Closed-loop**: harvest extracts → stores → downstream consumers (wiki-digest, spec-load, maestro-plan --gaps).
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/harvest.md
-</required_reading>
-
-<context>
-$ARGUMENTS — session-id, path, or empty for scan mode.
-
-**Modes:**
-- No args → `scan`: discover all harvestable artifacts, interactive selection
-- `<session-id>` → `session`: harvest specific session
-- `<path>` → `path`: harvest from explicit directory
-
-**Flags:**
-- `--to <target>` — Force routing: wiki, spec, issue, auto (default: auto)
-- `--source <type>` — Filter: analysis, brainstorm, debug, lite-plan, lite-fix, scratchpad, session, learning, all
-- `--recent N` — Artifacts within last N days (default: 30)
-- `--dry-run` — Preview without writing
-- `-y` — Skip confirmations
-- `--min-confidence N` — Minimum 0.0-1.0 (default: 0.5)
-
-**Source registry:**
-| Source | Scan Path | Key Files |
-|--------|-----------|-----------|
-| analysis | `.workflow/.analysis/ANL-*/` | conclusions.json |
-| brainstorm | `.workflow/scratch/brainstorm-*/` | guidance-specification.md |
-| lite-plan | `.workflow/.lite-plan/*/` | plan.json |
-| lite-fix | `.workflow/.lite-fix/*/` | fix-plan.json |
-| debug | `.workflow/.debug/*/` | debug-log.md |
-| scratchpad | `.workflow/.scratchpad/` | *.md |
-| session | `.workflow/active/WFS-*/` | workflow-session.json |
-| learning | `.workflow/learning/` | lessons.jsonl |
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/harvest.md' Stages 1–8.
-
-**Key invariants:**
-1. **Read-only until Stage 6** — extraction/classification in-memory only
-2. **Dedup before write** — check harvest-log.jsonl + existing stores
-3. **Stable fragment IDs** — `HRV-{8 hex}` from `hash(source_id + content_hash)`
-4. **Never modify source artifacts** — purely extractive
-5. **Confidence filtering** — below threshold logged but not routed
-6. **Spec format enforcement** — all spec routing must use `<spec-entry>` closed-tag format with `category`, `keywords`, `date`, `source="harvest"` attributes
-
-**Routing rules:**
-- Universal design patterns → `coding` or `arch` category
-- Component-level pitfalls → `learning` category
-- Quality enforcement rules → `quality` category
-- Wiki: `maestro wiki create --type <type> --slug harvest-<source_type>-<short_id>`
-- Spec: `maestro wiki append spec-<file> --category <category> --body "<content>" --keywords "<kws>"` (unified write path) or `Skill({ skill: "spec-add", args: "<category> <content>" })`
-- Issue: append to `issues.jsonl` matching canonical schema
-
-**Next steps:** `/manage-wiki health`, `maestro wiki list --type note`, `/wiki-connect --fix`, `/wiki-digest`, `/manage-issue list --source harvest`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | .workflow/ not initialized | Run $maestro-init |
-| E002 | error | Invalid --to target | Valid: wiki, spec, issue, auto |
-| E003 | error | Invalid --source type | Display valid types |
-| E004 | error | Session ID not found | Show available sessions |
-| W001 | warning | No harvestable artifacts in window | Widen --recent |
-| W003 | warning | Fragments below threshold | Lower --min-confidence |
-| W004 | warning | Duplicate fragments skipped | Review harvest-log.jsonl |
-</error_codes>
-
-<success_criteria>
-- [ ] Mode resolved (scan / session / path)
-- [ ] Artifacts discovered and parsed
-- [ ] Fragments extracted with category, confidence, tags
-- [ ] Dedup check passed against harvest-log.jsonl and stores
-- [ ] If not dry-run: routed items written to target stores
-- [ ] harvest-log.jsonl updated with provenance
-- [ ] harvest-report-{date}.md written
-- [ ] No source artifacts modified
-</success_criteria>
+---
+name: manage-harvest
+description: Extract knowledge from artifacts into wiki/spec/issues
+argument-hint: "[<session-id|path>] [--to wiki|spec|issue|auto] [--source <type>] [--recent N] [--dry-run] [-y]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Knowledge extraction from workflow artifacts, routed into three stores: wiki entries,
+spec conventions, and trackable issues. Prevents knowledge loss from completed sessions.
+
+**Closed-loop**: harvest extracts → stores → downstream consumers (wiki-digest, spec-load, maestro-plan --gaps).
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/harvest.md
+</required_reading>
+
+<context>
+$ARGUMENTS — session-id, path, or empty for scan mode.
+
+**Modes:**
+- No args → `scan`: discover all harvestable artifacts, interactive selection
+- `<session-id>` → `session`: harvest specific session
+- `<path>` → `path`: harvest from explicit directory
+
+**Flags:**
+- `--to <target>` — Force routing: wiki, spec, issue, auto (default: auto)
+- `--source <type>` — Filter: analysis, brainstorm, debug, lite-plan, lite-fix, scratchpad, session, learning, all
+- `--recent N` — Artifacts within last N days (default: 30)
+- `--dry-run` — Preview without writing
+- `-y` — Skip confirmations
+- `--min-confidence N` — Minimum 0.0-1.0 (default: 0.5)
+
+**Source registry:**
+| Source | Scan Path | Key Files |
+|--------|-----------|-----------|
+| analysis | `.workflow/.analysis/ANL-*/` | conclusions.json |
+| brainstorm | `.workflow/scratch/brainstorm-*/` | guidance-specification.md |
+| lite-plan | `.workflow/.lite-plan/*/` | plan.json |
+| lite-fix | `.workflow/.lite-fix/*/` | fix-plan.json |
+| debug | `.workflow/.debug/*/` | debug-log.md |
+| scratchpad | `.workflow/.scratchpad/` | *.md |
+| session | `.workflow/active/WFS-*/` | workflow-session.json |
+| learning | `.workflow/learning/` | lessons.jsonl |
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/harvest.md' Stages 1–8.
+
+**Key invariants:**
+1. **Read-only until Stage 6** — extraction/classification in-memory only
+2. **Dedup before write** — check harvest-log.jsonl + existing stores
+3. **Stable fragment IDs** — `HRV-{8 hex}` from `hash(source_id + content_hash)`
+4. **Never modify source artifacts** — purely extractive
+5. **Confidence filtering** — below threshold logged but not routed
+6. **Spec format enforcement** — all spec routing must use `<spec-entry>` closed-tag format with `category`, `keywords`, `date`, `source="harvest"` attributes
+
+**Routing rules:**
+- Universal design patterns → `coding` or `arch` category
+- Component-level pitfalls → `learning` category
+- Quality enforcement rules → `quality` category
+- Wiki: `maestro wiki create --type <type> --slug harvest-<source_type>-<short_id>`
+- Spec: `maestro wiki append spec-<file> --category <category> --body "<content>" --keywords "<kws>"` (unified write path) or `Skill({ skill: "spec-add", args: "<category> <content>" })`
+- Issue: append to `issues.jsonl` matching canonical schema
+
+**Next steps:** `/manage-wiki health`, `maestro wiki list --type note`, `/wiki-connect --fix`, `/wiki-digest`, `/manage-issue list --source harvest`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | .workflow/ not initialized | Run $maestro-init |
+| E002 | error | Invalid --to target | Valid: wiki, spec, issue, auto |
+| E003 | error | Invalid --source type | Display valid types |
+| E004 | error | Session ID not found | Show available sessions |
+| W001 | warning | No harvestable artifacts in window | Widen --recent |
+| W003 | warning | Fragments below threshold | Lower --min-confidence |
+| W004 | warning | Duplicate fragments skipped | Review harvest-log.jsonl |
+</error_codes>
+
+<success_criteria>
+- [ ] Mode resolved (scan / session / path)
+- [ ] Artifacts discovered and parsed
+- [ ] Fragments extracted with category, confidence, tags
+- [ ] Dedup check passed against harvest-log.jsonl and stores
+- [ ] If not dry-run: routed items written to target stores
+- [ ] harvest-log.jsonl updated with provenance
+- [ ] harvest-report-{date}.md written
+- [ ] No source artifacts modified
+</success_criteria>

package/.codex/skills/manage-issue/SKILL.md

@@ -1,15 +1,21 @@
 ---
 name: manage-issue
-description: Issue CRUD -- create, list, status, update, close, and link issues to tasks
+description: Create, query, update, close, and link issues
 argument-hint: "<create|list|status|update|close|link> [options]"
-allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
 <purpose>
 Issue CRUD operations: create, list, status, update, close, and link issues to tasks.
 All data stored in `.workflow/issues/issues.jsonl` with auto-created directory on first use.
+
+**Closed-loop workflow**: issue → `$maestro-analyze --gaps <ISS-ID>` (root cause analysis) → `$maestro-plan --gaps` (solution planning) → `$maestro-execute` (implementation). For automated issue discovery, use `$manage-issue-discover`.
 </purpose>
 
+<required_reading>
+Read `~/.maestro/workflows/issue.md` before executing any subcommand. This file defines the issue.json schema, ID format, field validation rules, and JSONL storage conventions.
+</required_reading>
+
 <context>
 $ARGUMENTS — subcommand followed by options.
 
@@ -34,11 +40,15 @@ If missing or invalid, display usage and prompt user (E_NO_SUBCOMMAND, E_INVALID
 
 ### Step 2: Ensure Storage
 
-Auto-create `.workflow/issues/` and empty `issues.jsonl` if missing (E_ISSUES_DIR_MISSING handled silently).
+If `.workflow/issues/` does not exist, auto-create the directory and write an empty `issues.jsonl` file. Log as E_ISSUES_DIR_MISSING (warning, non-blocking).
 
 ### Step 3: Execute Subcommand
 
-**create**: Read `~/.maestro/templates/issue.json` for schema. Generate ID `ISS-{YYYYMMDD}-{NNN}`. Prompt for missing required fields (title, severity). Append JSON line to `issues.jsonl`.
+**create**: Read `~/.maestro/templates/issue.json` for schema. Generate ID `ISS-{YYYYMMDD}-{NNN}`. If required fields are missing, prompt via `request_user_input`:
+```json
+{ "questions": [{ "id": "issue_title", "header": "New Issue", "question": "What is the issue title?" }, { "id": "issue_severity", "header": "Issue Severity", "question": "What severity level?", "options": [{ "label": "high (Recommended)", "description": "Production-impacting or blocking" }, { "label": "medium", "description": "Degraded functionality" }, { "label": "low", "description": "Minor or cosmetic" }] }] }
+```
+Append JSON line to `issues.jsonl`.
 
 **list**: Read `issues.jsonl`, filter by `--status`, `--phase`, `--severity`, `--source`. Display as table:
 ```
@@ -52,7 +62,10 @@ ISS-20260318-001 | high     | open   | Auth token expiry bug
 
 **close**: Find issue by ID, set status to `closed`, add `resolution` and `closed_at`. Move line from `issues.jsonl` to `issue-history.jsonl`.
 
-**link**: Find issue by ID, add task reference to issue's `linked_tasks` array. If task JSON exists (`.task/TASK-*.json`), add issue reference to task's `linked_issues`. Bidirectional cross-reference.
+**link**: Bidirectional cross-reference between issue and task:
+1. Find issue by ID in `issues.jsonl`, add task ID to issue's `linked_tasks[]` array, rewrite the line
+2. Read task JSON at `.workflow/.task/{TASK-ID}.json` (or `.task/{TASK-ID}.json`). Edit the task's `linked_issues` field — append the issue ID to the array. If `linked_issues` field does not exist, create it as `[ISS-ID]`
+3. Both writes must succeed for the link to be considered complete
 </execution>
 
 <error_codes>
@@ -60,7 +73,7 @@ ISS-20260318-001 | high     | open   | Auth token expiry bug
 |------|----------|-------------|
 | E_NO_SUBCOMMAND | error | No subcommand provided -- display valid subcommands |
 | E_INVALID_SUBCOMMAND | error | Unrecognized subcommand |
-| E_ISSUES_DIR_MISSING | warning | `.workflow/issues/` not found -- auto-created |
+| E_ISSUES_DIR_MISSING | warning | `.workflow/issues/` not found — auto-create directory and empty issues.jsonl |
 </error_codes>
 
 <success_criteria>

package/.codex/skills/manage-issue-discover/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: manage-issue-discover
-description: Multi-perspective issue discovery via CSV wave pipeline. 8 parallel perspective agents scan the codebase independently, then a dedup agent aggregates and creates issues. Replaces manage-issue-discover command.
+description: Discover issues via multi-perspective analysis
 argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"[by-prompt 'what to look for']\""
 allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 ---