@jakkrichm/create-nexus-devflow 2.0.0

package/template/.agents/skills/idea-refine/frameworks.md

@@ -0,0 +1,99 @@
+# Ideation Frameworks Reference
+
+Use these frameworks selectively. Pick the lens that fits the idea — don't mechanically run every framework. The goal is to unlock thinking, not to follow a checklist.
+
+## SCAMPER
+
+A structured way to transform an existing idea by applying seven different operations:
+
+- **Substitute:** What component, material, or process could you swap out? What if you replaced the core technology? The target audience? The business model?
+- **Combine:** What if you merged this with another product, service, or idea? What two things that don't usually go together would create something new?
+- **Adapt:** What else is like this? What ideas from other industries, domains, or time periods could you borrow? What parallel exists in nature?
+- **Modify (Magnify/Minimize):** What if you made it 10x bigger? 10x smaller? What if you exaggerated one feature? What if you stripped it to the absolute minimum?
+- **Put to other uses:** Who else could use this? What other problems could it solve? What happens if you use it in a completely different context?
+- **Eliminate:** What happens if you remove a feature entirely? What's the version with zero configuration? What would it look like with half the steps?
+- **Reverse/Rearrange:** What if you did the steps in the opposite order? What if the user did the work instead of the system (or vice versa)? What if you reversed the value chain?
+
+**Best for:** Improving or reimagining existing products/features. Less useful for greenfield ideas.
+
+## How Might We (HMW)
+
+Reframe problems as opportunities using the "How Might We..." format:
+
+- Start with an observation or pain point
+- Reframe it as "How might we [desired outcome] for [specific user] without [key constraint]?"
+- Generate multiple HMW framings of the same problem — different framings unlock different solutions
+
+**Good HMW qualities:**
+- Narrow enough to be actionable ("...help new users find relevant content in their first 5 minutes")
+- Broad enough to allow creative solutions (not "...add a recommendation sidebar")
+- Contains a tension or constraint that forces creativity
+
+**Bad HMW qualities:**
+- Too broad: "How might we make users happy?"
+- Too narrow: "How might we add a button to the settings page?"
+- Solution-embedded: "How might we build a chatbot for support?"
+
+**Best for:** Reframing stuck thinking. When someone is anchored on a solution, pull them back to the problem.
+
+## First Principles Thinking
+
+Break the idea down to its fundamental truths, then rebuild from there:
+
+1. **What do we know is true?** (not assumed, not conventional — actually true)
+2. **What are we assuming?** List every assumption, even the ones that feel obvious
+3. **Which assumptions can we challenge?** For each, ask: "Is this actually a law of physics, or just how it's been done?"
+4. **Rebuild from the truths.** If you only had the fundamental truths, what would you build?
+
+**Best for:** Breaking out of incremental thinking. When every idea feels like a small improvement on the status quo.
+
+## Jobs to Be Done (JTBD)
+
+Focus on what the user is trying to accomplish, not what they say they want:
+
+- **Functional job:** What task are they trying to complete?
+- **Emotional job:** How do they want to feel?
+- **Social job:** How do they want to be perceived?
+
+Format: "When I [situation], I want to [motivation], so I can [expected outcome]."
+
+**Key insight:** People don't buy products — they hire them to do a job. The competing product isn't always in the same category. (Netflix competes with sleep, not just other streaming services.)
+
+**Best for:** Understanding the real problem. When you're not sure if you're solving the right thing.
+
+## Constraint-Based Ideation
+
+Deliberately impose constraints to force creative solutions:
+
+- **Time constraint:** "What if you only had 1 day to build this?"
+- **Feature constraint:** "What if it could only have one feature?"
+- **Tech constraint:** "What if you couldn't use [the obvious technology]?"
+- **Cost constraint:** "What if it had to be free forever?"
+- **Audience constraint:** "What if your user had never used a computer before?"
+- **Scale constraint:** "What if it needed to work for 1 billion users? What about just 10?"
+
+**Best for:** Cutting through complexity. When the idea is growing too large or too vague.
+
+## Pre-mortem
+
+Imagine the idea has already failed. Work backwards:
+
+1. It's 12 months from now. The project shipped and flopped. What went wrong?
+2. List every plausible reason for failure — technical, market, team, timing
+3. For each failure mode: Is this preventable? Is this a signal the idea needs to change?
+4. Which failure modes are you willing to accept? Which ones would kill the project?
+
+**Best for:** Phase 2 evaluation. Stress-testing ideas that feel good but haven't been pressure-tested.
+
+## Analogous Inspiration
+
+Look at how other domains solved similar problems:
+
+- What industry has already solved a version of this problem?
+- What would this look like if [specific company/product] built it?
+- What natural system works this way?
+- What historical precedent exists?
+
+The key is finding *structural* similarities, not surface-level ones. "Uber for X" is surface-level. "A two-sided marketplace that solves a trust problem between strangers" is structural.
+
+**Best for:** Phase 1 expansion. Generating variations that feel genuinely different from the obvious approach.

package/template/.agents/skills/idea-refine/refinement-criteria.md

@@ -0,0 +1,113 @@
+# Refinement & Evaluation Criteria
+
+Use this rubric during Phase 2 (Evaluate & Converge) to stress-test idea directions. Not every criterion applies to every idea — use judgment about which dimensions matter most for the specific context.
+
+## Core Evaluation Dimensions
+
+### 1. User Value
+
+The most important dimension. If the value isn't clear, nothing else matters.
+
+**Painkiller vs. Vitamin:**
+- **Painkiller:** Solves an acute, frequent problem. Users will actively seek this out. They'll switch from their current solution. Signs: people describe the problem with emotion, they've built workarounds, they'll pay for a solution.
+- **Vitamin:** Nice to have. Makes something marginally better. Users won't go out of their way. Signs: people nod politely, say "that's cool," then don't change behavior.
+
+**Questions to ask:**
+- Can you name 3 specific people who have this problem right now?
+- What are they doing today instead? (The real competitor is always the current workaround.)
+- Would they switch from their current approach? What would make them switch?
+- How often do they encounter this problem? (Daily problems > monthly problems)
+- Is this a "pull" problem (users are asking for this) or a "push" problem (you think they should want this)?
+
+**Red flags:**
+- "Everyone could use this" — if you can't name a specific user, the value isn't clear
+- "It's like X but better" — marginal improvements rarely drive adoption
+- The problem is real but rare — high intensity but low frequency rarely justifies a product
+
+### 2. Feasibility
+
+Can you actually build this? Not just technically, but practically.
+
+**Technical feasibility:**
+- Does the core technology exist and work reliably?
+- What's the hardest technical problem? Is it a known-hard problem or a novel one?
+- Are there dependencies on third parties, APIs, or data sources you don't control?
+- What's the minimum technical stack needed? (If the answer is "a lot," that's a signal.)
+
+**Resource feasibility:**
+- What's the minimum team/effort to build an MVP?
+- Does it require specialized expertise you don't have?
+- Are there regulatory, legal, or compliance requirements?
+
+**Time-to-value:**
+- How quickly can you get something in front of users?
+- Is there a version that delivers value in days/weeks, not months?
+- What's the critical path? What has to happen first?
+
+**Red flags:**
+- "We just need to solve [very hard research problem] first"
+- Multiple dependencies that all need to work simultaneously
+- MVP still requires months of work — likely not minimal enough
+
+### 3. Differentiation
+
+What makes this genuinely different? Not better — *different*.
+
+**Questions to ask:**
+- If a user described this to a friend, what would they say? Is that description compelling?
+- What's the one thing this does that nothing else does? (If you can't name one, that's a problem.)
+- Is this differentiation durable? Can a competitor copy it in a week?
+- Is the difference something users actually care about, or just something builders find interesting?
+
+**Types of differentiation (strongest to weakest):**
+1. **New capability:** Does something that was previously impossible
+2. **10x improvement:** So much better on a key dimension that it changes behavior
+3. **New audience:** Brings an existing capability to people who were excluded
+4. **New context:** Works in a situation where existing solutions fail
+5. **Better UX:** Same capability, dramatically simpler experience
+6. **Cheaper:** Same thing, lower cost (weakest — easily competed away)
+
+**Red flags:**
+- Differentiation is entirely about technology, not user experience
+- "We're faster/cheaper/prettier" without a structural reason why
+- The feature that differentiates is not the feature users care most about
+
+## Assumption Audit
+
+For every idea direction, explicitly list assumptions in three categories:
+
+### Must Be True (Dealbreakers)
+Assumptions that, if wrong, kill the idea entirely. These need validation before building.
+
+Example: "Users will share their data with us" — if they won't, the entire product doesn't work.
+
+### Should Be True (Important)
+Assumptions that significantly impact success but don't kill the idea. You can adjust the approach if these are wrong.
+
+Example: "Users prefer self-serve over talking to a person" — if wrong, you need a different go-to-market, but the core product can still work.
+
+### Might Be True (Nice to Have)
+Assumptions about secondary features or optimizations. Don't validate these until the core is proven.
+
+Example: "Users will want to share their results with teammates" — a growth feature, not a core value proposition.
+
+## Decision Framework
+
+When choosing between directions, rank on this matrix:
+
+|                    | High Feasibility | Low Feasibility |
+|--------------------|-------------------|-----------------|
+| **High Value**     | Do this first     | Worth the risk   |
+| **Low Value**      | Only if trivial   | Don't do this    |
+
+Then use differentiation as the tiebreaker between options in the same quadrant.
+
+## MVP Scoping Principles
+
+When defining MVP scope for the chosen direction:
+
+1. **One job, done well.** The MVP should nail exactly one user job. Not three jobs done partially.
+2. **The riskiest assumption first.** The MVP's primary purpose is to test the assumption most likely to be wrong.
+3. **Time-box, not feature-list.** "What can we build and test in [timeframe]?" is better than "What features do we need?"
+4. **The 'Not Doing' list is mandatory.** Explicitly name what you're cutting and why. This prevents scope creep and forces honest prioritization.
+5. **If it's not embarrassing, you waited too long.** The first version should feel incomplete to the builder. If it doesn't, you over-built.

package/template/.agents/skills/idea-refine/scripts/idea-refine.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+set -e
+
+# This script helps initialize the ideas directory for the idea-refine skill.
+
+IDEAS_DIR="docs/ideas"
+
+if [ ! -d "$IDEAS_DIR" ]; then
+  mkdir -p "$IDEAS_DIR"
+  echo "Created directory: $IDEAS_DIR" >&2
+else
+  echo "Directory already exists: $IDEAS_DIR" >&2
+fi
+
+echo "{\"status\": \"ready\", \"directory\": \"$IDEAS_DIR\"}"

package/template/.agents/skills/incremental-implementation/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: incremental-implementation
+description: Delivers changes incrementally. Use when implementing any feature or change that touches more than one file. Use when you're about to write a large amount of code at once, or when a task feels too big to land in one step.
+---
+
+# Incremental Implementation
+
+## Overview
+
+Build in thin vertical slices — implement one piece, test it, verify it, then expand. Avoid implementing an entire feature in one pass. Each increment should leave the system in a working, testable state. This is the execution discipline that makes large features manageable.
+
+## When to Use
+
+- Implementing any multi-file change
+- Building a new feature from a task breakdown
+- Refactoring existing code
+- Any time you're tempted to write more than ~100 lines before testing
+
+**When NOT to use:** Single-file, single-function changes where the scope is already minimal.
+
+## The Increment Cycle
+
+```
+┌──────────────────────────────────────┐
+│                                      │
+│   Implement ──→ Test ──→ Verify ──┐  │
+│       ▲                           │  │
+│       └───── Commit ◄─────────────┘  │
+│              │                       │
+│              ▼                       │
+│          Next slice                  │
+│                                      │
+└──────────────────────────────────────┘
+```
+
+For each slice:
+
+1. **Implement** the smallest complete piece of functionality
+2. **Test** — run the test suite (or write a test if none exists)
+3. **Verify** — confirm the slice works as expected (tests pass, build succeeds, manual check)
+4. **Commit** -- save your progress with a descriptive message (see `git-workflow-and-versioning` for atomic commit guidance)
+5. **Move to the next slice** — carry forward, don't restart
+
+## Slicing Strategies
+
+### Vertical Slices (Preferred)
+
+Build one complete path through the stack:
+
+```
+Slice 1: Create a task (DB + API + basic UI)
+    → Tests pass, user can create a task via the UI
+
+Slice 2: List tasks (query + API + UI)
+    → Tests pass, user can see their tasks
+
+Slice 3: Edit a task (update + API + UI)
+    → Tests pass, user can modify tasks
+
+Slice 4: Delete a task (delete + API + UI + confirmation)
+    → Tests pass, full CRUD complete
+```
+
+Each slice delivers working end-to-end functionality.
+
+### Contract-First Slicing
+
+When backend and frontend need to develop in parallel:
+
+```
+Slice 0: Define the API contract (types, interfaces, OpenAPI spec)
+Slice 1a: Implement backend against the contract + API tests
+Slice 1b: Implement frontend against mock data matching the contract
+Slice 2: Integrate and test end-to-end
+```
+
+### Risk-First Slicing
+
+Tackle the riskiest or most uncertain piece first:
+
+```
+Slice 1: Prove the WebSocket connection works (highest risk)
+Slice 2: Build real-time task updates on the proven connection
+Slice 3: Add offline support and reconnection
+```
+
+If Slice 1 fails, you discover it before investing in Slices 2 and 3.
+
+## Implementation Rules
+
+### Rule 0: Simplicity First
+
+Before writing any code, ask: "What is the simplest thing that could work?"
+
+After writing code, review it against these checks:
+- Can this be done in fewer lines?
+- Are these abstractions earning their complexity?
+- Would a staff engineer look at this and say "why didn't you just..."?
+- Am I building for hypothetical future requirements, or the current task?
+
+```
+SIMPLICITY CHECK:
+✗ Generic EventBus with middleware pipeline for one notification
+✓ Simple function call
+
+✗ Abstract factory pattern for two similar components
+✓ Two straightforward components with shared utilities
+
+✗ Config-driven form builder for three forms
+✓ Three form components
+```
+
+Three similar lines of code is better than a premature abstraction. Implement the naive, obviously-correct version first. Optimize only after correctness is proven with tests.
+
+### Rule 0.5: Scope Discipline
+
+Touch only what the task requires.
+
+Do NOT:
+- "Clean up" code adjacent to your change
+- Refactor imports in files you're not modifying
+- Remove comments you don't fully understand
+- Add features not in the spec because they "seem useful"
+- Modernize syntax in files you're only reading
+
+If you notice something worth improving outside your task scope, note it — don't fix it:
+
+```
+NOTICED BUT NOT TOUCHING:
+- src/utils/format.ts has an unused import (unrelated to this task)
+- The auth middleware could use better error messages (separate task)
+→ Want me to create tasks for these?
+```
+
+### Rule 1: One Thing at a Time
+
+Each increment changes one logical thing. Don't mix concerns:
+
+**Bad:** One commit that adds a new component, refactors an existing one, and updates the build config.
+
+**Good:** Three separate commits — one for each change.
+
+### Rule 2: Keep It Compilable
+
+After each increment, the project must build and existing tests must pass. Don't leave the codebase in a broken state between slices.
+
+### Rule 3: Feature Flags for Incomplete Features
+
+If a feature isn't ready for users but you need to merge increments:
+
+```typescript
+// Feature flag for work-in-progress
+const ENABLE_TASK_SHARING = process.env.FEATURE_TASK_SHARING === 'true';
+
+if (ENABLE_TASK_SHARING) {
+  // New sharing UI
+}
+```
+
+This lets you merge small increments to the main branch without exposing incomplete work.
+
+### Rule 4: Safe Defaults
+
+New code should default to safe, conservative behavior:
+
+```typescript
+// Safe: disabled by default, opt-in
+export function createTask(data: TaskInput, options?: { notify?: boolean }) {
+  const shouldNotify = options?.notify ?? false;
+  // ...
+}
+```
+
+### Rule 5: Rollback-Friendly
+
+Each increment should be independently revertable:
+
+- Additive changes (new files, new functions) are easy to revert
+- Modifications to existing code should be minimal and focused
+- Database migrations should have corresponding rollback migrations
+- Avoid deleting something in one commit and replacing it in the same commit — separate them
+
+## Working with Agents
+
+When directing an agent to implement incrementally:
+
+```
+"Let's implement Task 3 from the plan.
+
+Start with just the database schema change and the API endpoint.
+Don't touch the UI yet — we'll do that in the next increment.
+
+After implementing, run `npm test` and `npm run build` to verify
+nothing is broken."
+```
+
+Be explicit about what's in scope and what's NOT in scope for each increment.
+
+## Increment Checklist
+
+After each increment, verify:
+
+- [ ] The change does one thing and does it completely
+- [ ] All existing tests still pass (`npm test`)
+- [ ] The build succeeds (`npm run build`)
+- [ ] Type checking passes (`npx tsc --noEmit`)
+- [ ] Linting passes (`npm run lint`)
+- [ ] The new functionality works as expected
+- [ ] The change is committed with a descriptive message
+
+## DevFlow 2.0 Progress Tracking
+
+During implementation, keep progress visible in markdown first:
+
+1. **Update `implement.md`**: Record the current slice, completed work, validation evidence, blockers, and next step.
+2. **Commit stage artifacts with code changes**: The implementation history should remain understandable from the repository, even without old dashboard tooling.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'll test it all at the end" | Bugs compound. A bug in Slice 1 makes Slices 2-5 wrong. Test each slice. |
+| "It's faster to do it all at once" | It *feels* faster until something breaks and you can't find which of 500 changed lines caused it. |
+| "These changes are too small to commit separately" | Small commits are free. Large commits hide bugs and make rollbacks painful. |
+| "I'll add the feature flag later" | If the feature isn't complete, it shouldn't be user-visible. Add the flag now. |
+| "This refactor is small enough to include" | Refactors mixed with features make both harder to review and debug. Separate them. |
+
+## Red Flags
+
+- More than 100 lines of code written without running tests
+- Multiple unrelated changes in a single increment
+- "Let me just quickly add this too" scope expansion
+- Skipping the test/verify step to move faster
+- Build or tests broken between increments
+- Large uncommitted changes accumulating
+- Building abstractions before the third use case demands it
+- Touching files outside the task scope "while I'm here"
+- Creating new utility files for one-time operations
+
+## Verification
+
+After completing all increments for a task:
+
+- [ ] Each increment was individually tested and committed
+- [ ] The full test suite passes
+- [ ] The build is clean
+- [ ] The feature works end-to-end as specified
+- [ ] No uncommitted changes remain

package/template/.agents/skills/insight/SKILL.md

@@ -0,0 +1,131 @@
+---name: insight
+
+description: Insight Extraction - Extract reusable lessons, file insights, patterns, gotchas, recommendations, and 9arm-skills/post-mortem learning from completed work.
+---
+
+# Phase 54: Insight Extraction
+
+## Target: $ARGUMENTS
+
+Use this workflow after implementation, QA, human approval, PR review, or a debugging session to preserve useful knowledge for future work.
+
+Primary behavior now lives in the `insight-capture` skill. Keep this workflow as the compatibility wrapper and knowledge-capture entry point.
+
+## Prompt Source
+
+Adapted from:
+
+- `insight_extractor.md`
+
+Additional credited discipline when the source work is a bug, regression, or incident:
+
+- `.agents/skills/9arm-skills/post-mortem/SKILL.md`
+- Source pack: `9arm-skills`
+- Credit: `thananon/9arm-skills`
+- Upstream: https://github.com/thananon/9arm-skills
+- Adapted for: Antigravity IDE / Nexus-DevFlow
+
+## Process
+
+### 1. Load Evidence
+
+Inspect the available evidence:
+
+- git diff or recent commits
+- `40-implement.md`
+- `50-verify.md`
+- `70-release.md`
+- `60-report.md`
+- modified files
+- human feedback or PR comments
+
+### 2. Extract Reusable Knowledge
+
+Capture only actionable knowledge:
+
+- file purpose and important changes
+- reusable patterns
+- gotchas and triggers
+- approach outcome
+- alternatives tried
+- context or token usage notes that explain avoidable overhead
+- recommendations for future sessions
+
+Avoid generic notes that do not help future work.
+
+For bug, regression, or incident work, apply the `post-mortem` lens only after fix and validation evidence exist:
+
+- what broke
+- impact
+- reliable repro or timeline
+- root cause
+- fix
+- validation evidence
+- why it slipped through
+- prevention or follow-up
+
+### 3. Save Or Route Insights
+
+Use the smallest durable destination:
+
+- stage artifacts when the lesson is specific to the current run
+- `devflow/lessons.md` for project-wide lessons
+- `/60-Report` for final narrative communication before release
+- `/70-Release` for release-facing notes and execution details
+
+For token/context learning, prefer the smallest concrete note:
+
+- what context was loaded unnecessarily
+- which file, artifact, or agent handoff caused repeated reading
+- what should be passed as minimal context next time
+- exact token counts only when they are available from the runtime or provider
+
+When updating `devflow/lessons.md`, inspect `.agent/resources/schemas/lessons.template.md` first and replace any placeholder text with concrete incident facts, insight, prevention, and follow-up action.
+
+If task logs are appropriate:
+
+If this insight must be tied back to the running work item, record it in `50-verify.md`, `60-report.md`, `70-release.md`, or `devflow/lessons.md` rather than a legacy task log command.
+
+## Output
+
+Return:
+
+- file insights
+- patterns discovered
+- gotchas discovered
+- approach outcome
+- context usage notes
+- recommendations
+- where the insight was recorded or should be recorded
+
+If `post-mortem` was applied, include a short `Source Discipline` note crediting `9arm-skills/post-mortem`.
+
+## Relationship To DevFlow 2.0
+
+- Classification: Companion command
+- Mainline status: Knowledge capture command, not a numbered stage
+- Typical entry points: after `Debug`, `/50-Verify`, incident work, or review findings
+- Typical handoff targets: `Wiki`, `/60-Report`, `Help`
+
+## Sources
+
+- `AGENTS.md`
+- `.agent/resources/schemas/lessons.template.md`
+- Related commands: `Debug`, `/50-Verify`, `Wiki`, `/60-Report`, `Help`
+
+## Next Workflow Recommendation
+
+- **Primary**: `Wiki project ingest {source}` when the insight is reusable project knowledge.
+- **Why**: `Insight` extracts lessons; `Wiki` compiles selected lessons into navigable knowledge pages.
+- **Alternatives**:
+  - `/60-Report {ID}` - choose this when the insight should become the final communication summary before release.
+  - `/70-Release {ID}` - choose this when the insight should shape release packaging or execution details.
+  - `Help {ID}` - choose this when the next route is unclear.
+
+## Wiki Update Recommendation
+
+- **Needed**: `yes` for reusable lessons, gotchas, decisions, validated root causes, or token/context optimizations.
+- **Scope**: `project` for target-project lessons, `framework` for DevFlow workflow lessons.
+- **Reason**: Insight extraction is the safest handoff point for wiki compilation.
+- **Suggested Command**: `Wiki project ingest {source}`
+

package/template/.agents/skills/insight-capture/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: insight-capture
+description: Extract durable lessons, patterns, gotchas, and post-mortem knowledge from completed work. Use when implementation or verification work should become reusable team knowledge.
+---
+
+# Insight Capture
+
+## Overview
+
+This skill is the shared behavior layer behind `Insight`.
+
+It preserves the valuable learning workflow from the legacy system while treating insight capture as a support capability rather than a numbered stage.
+
+## Related Foundation Skills
+
+This skill should reuse and align with:
+
+- `.agents/skills/9arm-skills/post-mortem/SKILL.md`
+- `.agent/resources/schemas/lessons.template.md`
+
+## When to Use
+
+- after `/50-Verify`, release preparation, or a completed implementation run
+- after debugging, regression fixes, or incidents that deserve durable learning
+- when reusable project knowledge should move into lessons, wiki material, or final reporting
+
+## Process
+
+### 1. Load Evidence
+
+Inspect only the evidence needed:
+
+- `implement.md`
+- `verify.md`
+- `release.md`
+- `report.md`
+- recent diff, commits, or review comments when relevant
+
+### 2. Extract Actionable Knowledge
+
+Capture only useful knowledge such as:
+
+- important file or behavior changes
+- reusable patterns
+- gotchas and triggers
+- approach outcome
+- alternatives tried
+- context loading waste or handoff overhead
+- recommendations for future runs
+
+### 3. Apply Post-Mortem When Needed
+
+For bug, regression, or incident work, use the `post-mortem` lens only after fix and validation evidence exist:
+
+- what broke
+- impact
+- repro or timeline
+- root cause
+- fix
+- validation evidence
+- why it slipped through
+- prevention or follow-up
+
+### 4. Save To The Smallest Durable Destination
+
+Prefer:
+
+- stage artifacts when the lesson is run-specific
+- `devflow/lessons.md` for project-wide knowledge
+- `Wiki` when the knowledge should become navigable team documentation
+- `/60-Report` when the lesson belongs in the final communication package before release
+
+When updating `devflow/lessons.md`, use `.agent/resources/schemas/lessons.template.md` and replace placeholder text completely.
+
+## Output
+
+Return:
+
+- lessons captured
+- patterns and gotchas
+- approach outcome
+- recommendations
+- where the insight was recorded
+- whether `Wiki` or `/60-Report` should be the next handoff