specsmd 0.0.0-dev.85 → 0.0.0-dev.87

package/flows/fire/agents/builder/skills/walkthrough-generate/SKILL.md

@@ -115,7 +115,7 @@ Generate implementation walkthrough for human review after run completion.
 <output_template>
   **Walkthrough** (`.specs-fire/runs/{run-id}/walkthrough.md`):
 
-  ```markdown
+  ````markdown
   ---
   run: {run-id}
   work_item: {work-item-id}
@@ -152,97 +152,100 @@ Generate implementation walkthrough for human review after run completion.
   └─────────────────────────────┘
   ```
 
-  ## Files Changed
+## Files Changed
 
-  ### Created
+### Created
 
   | File | Purpose |
   |------|---------|
   | `{path}` | {purpose} |
 
-  ### Modified
+### Modified
 
   | File | Changes |
   |------|---------|
   | `{path}` | {changes} |
 
-  ## Domain Model (if entities created)
+## Domain Model (if entities created)
 
-  ### Entities
+### Entities
 
   | Entity | Properties | Business Rules |
   |--------|------------|----------------|
   | {name} | {props} | {rules} |
 
-  ### Value Objects
+### Value Objects
 
   | Value Object | Properties | Constraints |
   |--------------|------------|-------------|
   | {name} | {props} | {constraints} |
 
-  ## Key Implementation Details
+## Key Implementation Details
 
-  ### 1. {Detail Title}
+### 1. {Detail Title}
 
   {description of implementation approach}
 
-  ## Security Considerations (if applicable)
+## Security Considerations (if applicable)
 
   | Concern | Approach |
   |---------|----------|
   | {concern} | {approach} |
 
-  ## Performance Considerations (if applicable)
+## Performance Considerations (if applicable)
 
   | Requirement | Implementation |
   |-------------|----------------|
   | {requirement} | {implementation} |
 
-  ## Decisions Made
+## Decisions Made
 
   | Decision | Choice | Rationale |
   |----------|--------|-----------|
   | {decision} | {choice} | {rationale} |
 
-  ## Deviations from Plan
+## Deviations from Plan
 
   {Changes from work item plan and why, or "None"}
 
-  ## Dependencies Added
+## Dependencies Added
 
   | Package | Why Needed |
   |---------|------------|
   | `{package}` | {reason} |
 
-  ## How to Verify
+## How to Verify
 
   1. **{Step Title}**
+
      ```bash
      {command}
      ```
+
      Expected: {expected output}
 
-  ## Test Coverage
+## Test Coverage
 
-  - Tests added: {count}
-  - Coverage: {percentage}%
-  - Status: {passing/failing}
+- Tests added: {count}
+- Coverage: {percentage}%
+- Status: {passing/failing}
 
-  ## Ready for Review
+## Ready for Review
 
-  - [x] All acceptance criteria met
-  - [x] Tests passing
-  - [x] No critical issues
-  - [ ] Documentation updated (if applicable)
-  - [x] Developer notes captured
+- [x] All acceptance criteria met
+- [x] Tests passing
+- [x] No critical issues
+- [ ] Documentation updated (if applicable)
+- [x] Developer notes captured
 
-  ## Developer Notes
+## Developer Notes
 
   {Gotchas, tips, or context for future work - keep brief}
 
   ---
   *Generated by specs.md - fabriqa.ai FIRE Flow Run {run-id}*
-  ```
+
+  ````
 
 </output_template>
 

package/flows/fire/agents/orchestrator/agent.md

@@ -103,7 +103,7 @@ You are the **Orchestrator Agent** for FIRE (Fast Intent-Run Engineering).
   runs:
     active: []  # List of active runs (supports multiple parallel runs)
     completed:
-      - id: run-001
+      - id: run-fabriqa-2026-001
         work_items:
           - id: login-endpoint
             intent: user-auth

package/flows/fire/agents/orchestrator/skills/status/SKILL.md

@@ -639,7 +639,7 @@ Detect inconsistencies and offer interactive resolution.
 
   ## Active Runs
 
-  - **Run**: run-002 | **Scope**: single
+  - **Run**: run-fabriqa-2026-002 | **Scope**: single
   - **Current Item**: session-management
   - **Started**: 2026-01-19T10:30:00Z
 
@@ -657,7 +657,7 @@ Detect inconsistencies and offer interactive resolution.
 
   | # | Type | Location | Issue | Suggested Fix |
   |---|------|----------|-------|---------------|
-  | 1 | 🟡 | run-002 | Run started 3 days ago, may be stale | Resume or abandon |
+  | 1 | 🟡 | run-fabriqa-2026-002 | Run started 3 days ago, may be stale | Resume or abandon |
   | 2 | 🔵 | login-endpoint | Frontmatter says 'pending' but state says 'completed' | Sync frontmatter |
   | 3 | 🟡 | analytics-dashboard.md | Work item on disk but not tracked | Add to state.yaml |
 

package/flows/fire/memory-bank.yaml

@@ -66,7 +66,7 @@ state:
       - active: "List of currently active runs (supports multiple parallel runs)"
       - completed: "List of completed runs with id, work_item, intent, completed timestamp"
     # Each run (active or completed) has:
-    #   - id: "Run ID (e.g., run-001)"
+    #   - id: "Run ID (e.g., run-fabriqa-2026-001)"
     #   - scope: "single | batch | wide"
     #   - work_items: "List of work items in this run"
     #   - current_item: "Work item currently being executed (active runs only)"
@@ -93,9 +93,9 @@ naming:
     note: "Kebab-case, action-oriented name"
 
   runs:
-    format: "run-{NNN}/"
-    example: "run-001/"
-    note: "Sequential 3-digit number, folder per run"
+    format: "run-{worktree}-{NNN}/"
+    example: "run-fabriqa-2026-001/"
+    note: "Sequential 3-digit number per worktree, folder per run"
     contents:
       - "run.md"           # Run log (created by init-run.cjs)
       - "plan.md"          # Implementation plan (ALL modes, created BEFORE implementation)

package/flows/ideation/agents/orchestrator/agent.md

@@ -70,9 +70,9 @@ You are the **Ideation Orchestrator** for specsmd.
   └── concept-briefs/      # Shaped concepts
   ```
 
-  - Create session on first Spark batch
-  - Update session.yaml at each phase transition
-  - Session ID format: `{topic-slug}-{YYYYMMDD}`
+- Create session on first Spark batch
+- Update session.yaml at each phase transition
+- Session ID format: `{topic-slug}-{YYYYMMDD}`
 </session_management>
 
 <flow_transitions>
@@ -83,10 +83,11 @@ You are the **Ideation Orchestrator** for specsmd.
   ```
 
   Users can also:
-  - Skip Spark (bring their own ideas to Flame)
-  - Skip Flame (bring evaluated ideas to Forge)
-  - Loop back (Forge → more Spark to explore new angles)
-  - Use any skill standalone
+
+- Skip Spark (bring their own ideas to Flame)
+- Skip Flame (bring evaluated ideas to Forge)
+- Loop back (Forge → more Spark to explore new angles)
+- Use any skill standalone
 </flow_transitions>
 
 <success_criteria>

package/flows/ideation/agents/orchestrator/skills/flame/SKILL.md

@@ -116,6 +116,7 @@ Evaluate ideas fairly through multiple perspectives. Surface hidden value, ident
 </flow>
 
 <output_artifacts>
+
   | Artifact | Location | Template |
   |----------|----------|----------|
   | Flame Report | `.specs-ideation/sessions/{id}/flame-report.md` | `./templates/flame-report.md.hbs` |

package/flows/ideation/agents/orchestrator/skills/flame/references/evaluation-criteria.md

@@ -53,7 +53,9 @@ The core evaluation matrix. Every idea gets scored on both axes.
 ## Secondary Criteria
 
 ### Novelty (1-5)
+
 How original is this idea?
+
 - 5: Never seen before — genuinely new
 - 4: New in this context — adapted from elsewhere
 - 3: Fresh take on existing concept
@@ -61,6 +63,7 @@ How original is this idea?
 - 1: Already exists / obvious
 
 ### Risk Profile
+
 - **Technical risk**: Can this be built?
 - **Market risk**: Will anyone want this?
 - **Adoption risk**: Will people change behavior for this?
@@ -69,6 +72,7 @@ How original is this idea?
 ## Aggregation
 
 The Flame Report presents:
+
 1. **Impact × Feasibility matrix** — visual positioning
 2. **Six Hats summary** — qualitative analysis per idea
 3. **User Red Hat** — gut feelings

package/flows/ideation/agents/orchestrator/skills/flame/references/six-hats-method.md

@@ -5,6 +5,7 @@
 ## Core Concept
 
 Instead of arguing different positions, everyone (or the AI) wears the same "hat" at the same time, exploring one perspective fully before moving to the next. This prevents:
+
 - **Ego defense** — ideas aren't "yours" or "mine"
 - **Argument** — you're not debating, you're exploring perspectives
 - **Incomplete analysis** — each hat forces a perspective that might be skipped
@@ -12,35 +13,41 @@ Instead of arguing different positions, everyone (or the AI) wears the same "hat
 ## The Six Hats
 
 ### White Hat — Facts & Data
+
 - What do we know for certain?
 - What data exists? What's missing?
 - No interpretation or opinion — just facts
 - **AI application**: State what's objectively true about the idea, what evidence supports it, what data would be needed
 
 ### Red Hat — Feelings & Intuition
+
 - What's the gut reaction?
 - Emotions, hunches, instincts — no justification needed
 - **AI application**: This is the ONE hat where user input is critical. AI should ask: "What's your gut feeling?" If user defers, AI infers from engagement patterns.
 
 ### Black Hat — Risks & Caution
+
 - What could go wrong?
 - Where are the dangers, weaknesses, pitfalls?
 - Devil's advocate perspective
 - **AI application**: Be genuinely critical — not token concerns. Identify real risks: market, technical, adoption, unintended consequences.
 
 ### Yellow Hat — Benefits & Optimism
+
 - What's the best case scenario?
 - Why could this work? What's the upside?
 - Look for value even in seemingly weak ideas
 - **AI application**: Find genuine strengths. For weak ideas, ask: "What kernel of value exists here?"
 
 ### Green Hat — Creative Extensions
+
 - How could this be improved, combined, extended?
 - New alternatives, modifications, provocations
 - This is the divergent hat within convergence
 - **AI application**: Suggest creative modifications, combinations with other ideas, unexpected extensions
 
 ### Blue Hat — Process & Planning
+
 - What would implementation look like?
 - What steps are needed? What's the timeline?
 - Meta-thinking about the idea
@@ -49,21 +56,26 @@ Instead of arguing different positions, everyone (or the AI) wears the same "hat
 ## Sequencing for Ideation Flow
 
 ### Rapid Evaluation Sequence (Flame default)
+
 ```
 White → Yellow → Black → Green → Blue
 ```
+
 Red Hat is handled separately (requires user input).
 
 **Rationale**:
+
 - Start with facts (ground the discussion)
 - Benefits before risks (prevents premature dismissal)
 - Creative extensions after critique (rescue and improve)
 - Process last (only relevant for shortlisted ideas)
 
 ### Full Sequence (for top shortlisted ideas)
+
 ```
 Blue → White → Red → Yellow → Black → Green → Blue
 ```
+
 Starting and ending with Blue provides process framing.
 
 ## AI Execution Notes

package/flows/ideation/agents/orchestrator/skills/forge/SKILL.md

@@ -137,6 +137,7 @@ Develop shortlisted ideas into polished, actionable concept briefs. AI and user
 </flow>
 
 <output_artifacts>
+
   | Artifact | Location | Template |
   |----------|----------|----------|
   | Concept Brief | `.specs-ideation/sessions/{id}/concept-briefs/{name}.md` | `./templates/concept-brief.md.hbs` |

package/flows/ideation/agents/orchestrator/skills/forge/references/disney-method.md

@@ -9,6 +9,7 @@ The same idea is examined through three completely separate lenses, in sequence.
 ## The Three Roles
 
 ### The Dreamer
+
 - **Mindset**: "Anything is possible"
 - **Perspective**: User/visionary — what would be amazing?
 - **Time horizon**: Infinite
@@ -16,6 +17,7 @@ The same idea is examined through three completely separate lenses, in sequence.
 - **Question**: "If we could do anything, what would this look like?"
 
 **AI behavior in Dreamer mode**:
+
 - Generate the most ambitious version of the idea
 - No "but" or "however" — pure expansion
 - Think about the emotional impact on users
@@ -23,6 +25,7 @@ The same idea is examined through three completely separate lenses, in sequence.
 - Use vivid, exciting language
 
 ### The Realist
+
 - **Mindset**: "How would this actually work?"
 - **Perspective**: Project manager/engineer — what's the plan?
 - **Time horizon**: 3-12 months
@@ -30,6 +33,7 @@ The same idea is examined through three completely separate lenses, in sequence.
 - **Question**: "What needs to be true for this to work?"
 
 **AI behavior in Realist mode**:
+
 - Break the dream into concrete components
 - Identify the minimum viable version
 - Map resources, skills, and technology needed
@@ -37,6 +41,7 @@ The same idea is examined through three completely separate lenses, in sequence.
 - Focus on what can be leveraged from existing work
 
 ### The Critic
+
 - **Mindset**: "What could go wrong?"
 - **Perspective**: Quality assurance/risk analyst — what are the weak spots?
 - **Time horizon**: Full lifecycle
@@ -44,6 +49,7 @@ The same idea is examined through three completely separate lenses, in sequence.
 - **Question**: "Why might this fail, and how do we prevent it?"
 
 **AI behavior in Critic mode**:
+
 - Identify genuine risks (not token concerns)
 - Challenge the weakest assumptions
 - Consider second-order effects and unintended consequences
@@ -72,6 +78,7 @@ The Forge skill uses Disney Strategy with a co-build emphasis:
 | **Critic** | AI raises concerns (generates 40%) | User identifies personal concerns and co-develops mitigations (60%) |
 
 The Critic phase has the highest user involvement because:
+
 - Users know their context, stakeholders, and politics better than AI
 - Risk assessment requires domain-specific knowledge
 - Co-developing mitigations builds ownership and confidence
@@ -79,6 +86,7 @@ The Critic phase has the highest user involvement because:
 ## Anti-Pattern: The Premature Critic
 
 The most common failure mode is jumping to critique too early. Signals:
+
 - "That won't work because..." (before the idea is fully developed)
 - "But what about..." (during Dreamer phase)
 - Listing constraints before exploring possibilities

package/flows/ideation/agents/orchestrator/skills/forge/references/pitch-framework.md

@@ -7,49 +7,60 @@ Structures for presenting concepts clearly and persuasively. Used when generatin
 Every Concept Brief follows this structure:
 
 ### 1. One-Liner
+
 A single sentence that captures the essence. If you can't say it in one sentence, the concept isn't clear enough.
 
 **Formula**: [Action] + [for whom] + [unique mechanism] + [key benefit]
 
 **Examples**:
+
 - "A quest-based onboarding system that turns new hire setup into a game, cutting time-to-productivity by 60%."
 - "A reverse mentoring platform where junior employees teach executives about emerging tech, building cross-generational understanding."
 
 ### 2. Problem
+
 What pain exists today? Be specific and vivid.
 
 **Formula**: [Who] + [experiences what pain] + [how often/severely] + [what it costs them]
 
 ### 3. Concept
+
 How does this solve the problem? What's the mechanism?
 
 **Elements**:
+
 - Core mechanism (how it works)
 - Key differentiator (why this approach vs. others)
 - User experience (what does the user see/feel/do?)
 
 ### 4. Why It Works
+
 What makes this concept compelling? Why will it succeed?
 
 **Types of evidence**:
+
 - Analogies that have worked elsewhere
 - Research or data that supports the approach
 - First-principles reasoning
 - User psychology insights
 
 ### 5. Risks & Mitigations
+
 What could go wrong, and what's the plan?
 
 **Format per risk**:
+
 - **Risk**: {what could go wrong}
 - **Likelihood**: Low / Medium / High
 - **Impact**: Low / Medium / High
 - **Mitigation**: {specific action to prevent or address}
 
 ### 6. Next Steps
+
 What would you do first to move this forward?
 
 **Good next steps are**:
+
 - Specific (not "do more research")
 - Actionable (can be started this week)
 - Time-bounded (has a deadline or milestone)
@@ -58,15 +69,19 @@ What would you do first to move this forward?
 ## Pitch Principles
 
 ### Specificity Over Abstraction
+
 - Bad: "Leverage gamification to improve engagement"
 - Good: "A quest system where each completed onboarding task unlocks a new tool, with a leaderboard showing progress vs. cohort average"
 
 ### Show, Don't Categorize
+
 - Bad: "This is a B2B SaaS solution for the enterprise market"
 - Good: "When a new VP of Engineering joins, they open their laptop and see a personalized roadmap..."
 
 ### One Problem, One Solution
+
 Each concept brief tackles one clear problem. If there are multiple problems, make multiple briefs.
 
 ### The "Tell a Friend" Test
+
 The one-liner should be something someone would actually say to a colleague: "Hey, have you heard about this thing that [one-liner]?"

package/flows/ideation/agents/orchestrator/skills/spark/SKILL.md

@@ -135,6 +135,7 @@ Generate genuinely diverse, surprising ideas through rapid batches. AI is the cr
 </flow>
 
 <output_artifacts>
+
   | Artifact | Location | Template |
   |----------|----------|----------|
   | Spark Bank | `.specs-ideation/sessions/{id}/spark-bank.md` | `./templates/spark-bank.md.hbs` |

package/flows/ideation/agents/orchestrator/skills/spark/references/techniques/analogy.md

@@ -14,31 +14,37 @@
 ## Analogy Sources
 
 ### Nature (Biomimicry)
+
 - How does nature solve similar problems?
 - Velcro from burrs, bullet trains from kingfisher beaks, self-healing materials from skin
 - Best for: structural, efficiency, and resilience problems
 
 ### Games & Sports
+
 - How do games create engagement, manage competition, handle fairness?
 - Matchmaking, progression systems, handicaps, spectator modes
 - Best for: engagement, fairness, and motivation problems
 
 ### Architecture & Urban Planning
+
 - How do cities manage flow, density, growth, safety?
 - Zoning, traffic patterns, public spaces, wayfinding
 - Best for: scale, navigation, and organization problems
 
 ### Music & Performance
+
 - How do musicians create tension, resolution, improvisation, collaboration?
 - Call-and-response, crescendo, variations on a theme
 - Best for: experience design, pacing, and collaboration problems
 
 ### History & Civilization
+
 - How did past civilizations solve similar problems?
 - Trade routes, governance, knowledge preservation, cultural transmission
 - Best for: communication, governance, and knowledge problems
 
 ### Medicine & Biology
+
 - How does the body handle similar challenges?
 - Immune system (threats), nervous system (signals), circulatory system (distribution)
 - Best for: security, communication, and distribution problems
@@ -46,6 +52,7 @@
 ## AI Application Notes
 
 When using analogy internally:
+
 1. Abstract the topic to its core challenge (e.g., "reduce onboarding time" → "accelerate knowledge transfer")
 2. Pick 2-3 distant domains from the list above
 3. Find genuine analogies (not surface-level similarities)

package/flows/ideation/agents/orchestrator/skills/spark/references/techniques/first-principles.md

@@ -15,18 +15,22 @@
 ## Decomposition Framework
 
 ### Layer 1: Surface (What people do)
+
 - Current behaviors, products, services
 - "Everyone does it this way because..."
 
 ### Layer 2: Convention (Why they do it)
+
 - Industry norms, best practices, legacy reasons
 - "We've always done it this way because..."
 
 ### Layer 3: Constraints (Real vs. assumed)
+
 - Physical laws, regulations, actual technical limits
 - vs. "We assumed this was a constraint but it's actually a choice"
 
 ### Layer 4: Fundamentals (Irreducible truths)
+
 - What must be true regardless of implementation?
 - What does the user actually need (not what they're used to)?
 - What are the physics/economics that can't be changed?
@@ -44,6 +48,7 @@
 ## AI Application Notes
 
 When using first-principles internally:
+
 1. Don't just list the fundamentals — actually strip away conventions and rebuild
 2. The power is in identifying which "constraints" are actually conventions
 3. Best used when ideas feel incremental — first-principles thinking produces category-shifting ideas

package/flows/ideation/agents/orchestrator/skills/spark/references/techniques/inversion.md

@@ -14,24 +14,29 @@
 ## Inversion Patterns
 
 ### Goal Inversion
+
 - Goal: "Make onboarding fast" → Inverted: "How to make onboarding take forever?"
 - Answers: No documentation, no buddy system, surprise requirements → Ideas: Pre-arrival portal, day-1 buddy auto-match, zero-surprise checklist
 
 ### User Inversion
+
 - Design for the opposite user: experts → beginners, individuals → teams, tech-savvy → tech-averse
 - Forces empathy and reveals assumptions
 
 ### Process Inversion
+
 - Reverse the order: What if the last step came first?
 - End-to-outcome: Start with the desired result and work backward
 - Often reveals unnecessary steps
 
 ### Value Inversion
+
 - What if the biggest cost became the biggest feature?
 - What if the bug became the selling point?
 - Turns weaknesses into differentiators
 
 ### Anti-Problem
+
 - Instead of solving the problem, make it irrelevant
 - Instead of reducing friction, make the friction delightful
 - Reframe rather than fix
@@ -39,6 +44,7 @@
 ## AI Application Notes
 
 When using inversion internally:
+
 1. Pick the most interesting inversion pattern for the current topic
 2. Actually go through the full inversion (state goal → invert → list failure modes → reverse)
 3. The best ideas come from reversing *non-obvious* failure modes

package/flows/ideation/agents/orchestrator/skills/spark/references/techniques/questorming.md

@@ -16,26 +16,31 @@
 ## Question Types
 
 ### Assumption-Challenging
+
 - Why do we assume [X] is necessary?
 - What if [commonly accepted truth] were false?
 - Who said this has to be done by [conventional actor]?
 
 ### Scope-Shifting
+
 - What if we zoom out 10x — what's the bigger problem?
 - What if we zoom in 10x — what's the specific pain point?
 - What would this look like from the customer's customer's perspective?
 
 ### Stakeholder Questions
+
 - Who benefits from the current broken state?
 - Who would lose if we solved this perfectly?
 - Who has already solved this in a different context?
 
 ### Temporal Questions
+
 - Why hasn't this been solved yet?
 - What will make this irrelevant in 5 years?
 - What had to change for this to become solvable now?
 
 ### Provocative Questions
+
 - What's the most expensive possible solution? The cheapest?
 - What would a competitor do with this opportunity?
 - What would a child suggest?
@@ -43,6 +48,7 @@
 ## AI Application Notes
 
 When using questorming internally:
+
 1. Generate a burst of 8-10 questions about the topic
 2. Present 3-5 of the most provocative ones to the user
 3. Ask: "Which of these feels most important?" (the one elicit moment)

package/flows/ideation/agents/orchestrator/skills/spark/references/techniques/random-word.md

@@ -27,6 +27,7 @@
 ## AI Application Notes
 
 When using random-word internally:
+
 1. Pick concepts from **distant domains** — nature, games, history, architecture, music
 2. The more unrelated the concept, the more novel the connections
 3. Generate at least 5 attribute-connections, then pick the 2-3 most surprising