@locksmithdon/dons-flow 2.0.0

package/skills/dons-flow/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: dons-flow
+description: Use when starting or navigating a major piece of work to apply the integrated RPIV + Superpowers-style workflow — discovery, research, design/plan, implement, validate, review, commit, and land
+---
+
+# Don's Flow
+
+**Version 2** of the integrated workflow for developer `@locksmithdon`: **RPIV's observable, artifact-chained delivery pipeline** plus **Superpowers' scope control, verification discipline, and cycle closeout**, with the `land` ritual that neither provides on its own.
+
+v1 was Superpowers-based with a custom landing ritual. v2 adds RPIV's pipeline while keeping the closeout, scope-control, and learning-capture practices.
+
+This skill is the map. It does not replace the skills it references — it tells you which skill to invoke when, and which conventions must stay true across all of them.
+
+Superpowers is the upstream methodology at [obra/superpowers](https://github.com/obra/superpowers). It is not published to npm under a resolvable name, so this package declares it as an optional git peer dependency (`github:obra/superpowers`). Install it via your agent harness's plugin system, via the git URL, or by forking and publishing it under your own scope.
+
+## Announce at start
+
+> "I'm using the `dons-flow` skill to run the integrated RPIV + Superpowers workflow."
+
+## When to use this skill
+
+- At the **start** of a new piece of work, to pick the right entry point.
+- When you are **mid-work** and unsure whether to keep going, hand off, revise, or close out.
+- At the **end** of a validated implementation, to begin the `land` closeout ritual.
+- When onboarding a fresh repo to this workflow.
+
+## Required installed packages
+
+This skill assumes the following Pi packages are installed:
+
+- `@juicesharp/rpiv-pi` — the RPIV pipeline skills
+- `@tintinweb/pi-subagents` — subagent runtime used by RPIV
+- `@locksmithdon/dons-flow` — this package, which adds closeout and discipline skills
+- `superpowers` — the upstream Superpowers methodology (optional, via harness plugin or `github:obra/superpowers`)
+
+If RPIV or the subagent runtime is missing, stop and install them before proceeding. If Superpowers is missing, this package's ported skills still provide the closeout workflow, but you will not have access to the upstream Superpowers entry points like `brainstorming` or `test-driven-development`.
+
+## Before you start
+
+If this repo has not been onboarded yet, run:
+
+```bash
+/skill:setup-dons-flow
+```
+
+That skill checks prerequisites, detects Superpowers, and creates the repo-owned conventions (`docs/tabled.md`, `docs/status.md`, `docs/memory/`, `docs/changes/`, `docs/retros/`, `docs/runbooks/`, `AGENTS.md`).
+
+## Integrated workflow
+
+```
+Discover → Research → Design/Blueprint → Plan → Implement → Validate → Review → Commit → Land
+```
+
+Each arrow is a skill invocation. Each skill produces or updates an artifact. Nothing is unilateral: every boundary is a conversation or a checkpoint.
+
+### 1. Discover — capture intent
+
+**Skill:** `/skill:discover "[feature description]"`
+
+**When:** The problem is not yet fully shaped; you need to extract goals, non-goals, constraints, acceptance criteria, and decisions before touching code.
+
+**What it produces:** `.rpiv/artifacts/discover/YYYY-MM-DD_HH-MM-SS_<topic>.md` — a Feature Requirements Document (FRD).
+
+**Integration note:** If you already have a written spec or ticket, pass its path to `discover` for refinement. For free-form ideation, run Superpowers `brainstorming` first and feed the result into `discover`.
+
+**End-of-artifact checkpoint:** After the FRD is written, run `capturing-learnings` before proceeding. Process any `docs/tabled.md` entries that surfaced during the interview.
+
+### 2. Research — ground intent in code
+
+**Skill:** `/skill:research .rpiv/artifacts/discover/<latest>.md`
+
+**When:** You have an FRD and need to understand the codebase reality that will shape the design.
+
+**What it produces:** `.rpiv/artifacts/research/<slug>_<topic>.md`
+
+**Integration note:** The FRD's `Decisions` block becomes research's Developer Context. Carry any unresolved Open Questions forward.
+
+**End-of-artifact checkpoint:** Run `capturing-learnings` after research is accepted.
+
+### 3. Design / Blueprint / Explore — decide the shape
+
+**Option A — compare approaches first:** `/skill:explore "[problem]"` → `/skill:design .rpiv/artifacts/solutions/<latest>.md`
+
+**Option B — full design artifact:** `/skill:design .rpiv/artifacts/research/<latest>.md`
+
+**Option C — fast path for smaller work:** `/skill:blueprint .rpiv/artifacts/research/<latest>.md`
+
+**When:** Multiple valid approaches exist → `explore`. The design is itself a deliverable or the work is large/cross-cutting → `design` then `plan`. The work is well-understood and you want an implement-ready plan in one pass → `blueprint`.
+
+**What it produces:**
+- `explore` → `.rpiv/artifacts/solutions/<slug>_<topic>.md`
+- `design` → `.rpiv/artifacts/designs/<slug>_<topic>.md`
+- `blueprint` → `.rpiv/artifacts/plans/<slug>_<topic>.md`
+
+**Integration note:** `blueprint` fuses `design` + `plan`. It is the closest RPIV equivalent to the Superpowers `writing-plans` + `subagent-driven-development` combo, but it is codebase-grounded and reviewed.
+
+**End-of-artifact checkpoint:** Run `capturing-learnings` after the design or plan is accepted.
+
+### 4. Plan — sequence the work
+
+**Skill:** `/skill:plan .rpiv/artifacts/designs/<latest>.md`
+
+**When:** You ran `design` separately and now need a phased implementation plan.
+
+**What it produces:** `.rpiv/artifacts/plans/<slug>_<topic>.md`
+
+**Integration note:** Skip this step if you used `blueprint`, which already emitted a plan.
+
+**End-of-artifact checkpoint:** Run `capturing-learnings` after the plan is accepted.
+
+### 5. Implement — execute phase by phase
+
+**Skill:** `/skill:implement .rpiv/artifacts/plans/<latest>.md [Phase N]`
+
+**When:** The plan is `status: ready`.
+
+**What it does:** Applies the plan's code changes to the working tree.
+
+**Integration notes:**
+- Keep `epiphany-tabling` active. Any realization, fork, or follow-up that is not trivially cheap and in-scope goes into `docs/tabled.md`.
+- Apply `verification-before-completion` discipline: no success claim without fresh verification evidence.
+- If a session ends mid-implementation, run `/skill:create-handoff`.
+- If code reality diverges from the plan, surface it via implement's mismatch flow or run `/skill:revise <plan-path>` first.
+
+### 6. Validate — verify against the plan
+
+**Skill:** `/skill:validate .rpiv/artifacts/plans/<latest>.md`
+
+**When:** Implementation is complete (or you need a checkpoint).
+
+**What it produces:** `.rpiv/artifacts/validation/<slug>_<topic>.md` with a `verdict: pass | fail`.
+
+**Integration note:** Do not proceed to `commit` or `land` if `verdict: fail`. Fix gaps, then re-run `validate`.
+
+### 7. Review — structured code review
+
+**Skill:** `/skill:code-review [scope]`
+
+**When:** After validate passes and before committing.
+
+**What it produces:** `.rpiv/artifacts/reviews/<slug>_<scope>.md`
+
+**Integration note:** The `land` skill's step 1 (code review) can consume this artifact. Fix small findings now; table substantive ones to `docs/tabled/`.
+
+### 8. Commit — atomic, logical commits
+
+**Skill:** `/skill:commit [message-hint]`
+
+**When:** The working tree contains validated changes ready to be committed.
+
+**What it does:** Groups staged/unstaged changes into logical commits.
+
+**Integration note:** On a feature branch, you may commit close-out artifacts (as-built, retro, memory updates) separately. On `main`, present commit groupings for human approval.
+
+### 9. Land — close the cycle
+
+**Skill:** `/skill:land`
+
+**When:** The implementation is verified, reviewed, and committed (or about to be merged).
+
+**What it does:** Runs the 10-step closeout ritual:
+
+1. Code review
+2. Architectural review
+3. Security review
+4. As-built documentation (`as-built-documentation`)
+5. Doc / knowledge-graph review
+6. AGENTS.md updates
+7. Memory reconcile
+8. Retro (`writing-retros`)
+9. Status review + resolve `docs/tabled.md`
+10. Integrate (`finishing-a-development-branch`)
+
+**Integration note:** `land` is the cycle boundary RPIV does not provide. It is the most important addition this package makes.
+
+## Monitoring the relationship
+
+We intentionally deferred deciding how to track Superpowers long-term. Review monthly using:
+
+- `docs/memory/monitor_upstream_evolution.md` — decision context and last review date
+- `docs/runbooks/monitor-upstream-evolution.md` — the check-in process
+
+After 2–3 projects, decide whether to keep the git peer dependency, fork Superpowers, or drop it.
+
+## Cross-cutting practices
+
+These practices run continuously across the workflow, not at a single stage.
+
+### Epiphany tabling
+
+Use `epiphany-tabling` whenever an unexpected realization surfaces mid-task. Add it to `docs/tabled.md`. Never lose it, never let it derail current work. Resolve tabled items at end-of-artifact checkpoints and during `land` step 9.
+
+### Verification before completion
+
+Before any completion claim — a test passing, a phase done, a feature working — run the verification command fresh, read the output, and cite the evidence. No shortcuts.
+
+### Capturing learnings
+
+After each approved artifact (FRD, research, design, plan, major commit set), run `capturing-learnings`. Apply the rule: **once is a moment; twice is a pattern.** Promote tabled observations to skills, runbooks, or memory only on the second sighting.
+
+### Handoffs
+
+If you must stop mid-work, use `/skill:create-handoff`. Resume with `/skill:resume-handoff .rpiv/artifacts/handoffs/<latest>.md` in a fresh session.
+
+## Repo conventions this workflow expects
+
+Your codebase should contain these documents and folders. They are owned by the team, not by any package:
+
+| Path | Purpose |
+|---|---|
+| `docs/tabled.md` | Working memory for epiphanies and deferred work |
+| `docs/tabled/` | Optional per-item tabled docs (resolved to empty each cycle) |
+| `docs/status.md` | Living status: Recently Completed, What's Next, etc. |
+| `docs/memory/` | Persistent project/session memory entries |
+| `docs/memory/MEMORY.md` | Index of memory entries |
+| `docs/changes/` | As-built documentation: what shipped and why |
+| `docs/retros/` | Frozen retrospective documents |
+| `docs/runbooks/` | Multi-skill processes and practices |
+| `AGENTS.md` | Repo-level agent guidance |
+
+## What lives in the codebase vs. what lives in the developer's package
+
+**In the codebase:** `docs/changes/`, `docs/retros/`, `docs/status.md`, `docs/memory/`, `AGENTS.md`, and the actual code changes.
+
+**In this package:** the skills, runbooks, and workflow conventions. They travel with the developer across repos.
+
+## Anti-patterns
+
+- **Skipping `land`.** `validate` is not the finish line. Close the cycle.
+- **Carrying `docs/tabled.md` across cycles.** Resolve every entry during `land` step 9.
+- **Editing source files during discover/research/design/plan.** Those skills produce artifacts; `implement` edits code.
+- **Recomposing RPIV slice boundaries.** `design`/`blueprint` owns decomposition; `plan` inherits slices 1:1.
+- **Letting verification become a rubber stamp.** Evidence first, claims second.
+
+## Quick reference
+
+| I want to... | Invoke |
+|---|---|
+| Onboard a repo | `/skill:setup-dons-flow` |
+| Capture intent | `/skill:discover "..."` |
+| Understand the codebase | `/skill:research <artifact-or-topic>` |
+| Compare options | `/skill:explore "..."` |
+| Design + plan separately | `/skill:design <research>` → `/skill:plan <design>` |
+| Design + plan together | `/skill:blueprint <research>` |
+| Execute the plan | `/skill:implement <plan> [Phase N]` |
+| Verify implementation | `/skill:validate <plan>` |
+| Review changes | `/skill:code-review [scope]` |
+| Commit changes | `/skill:commit` |
+| Close out the cycle | `/skill:land` |
+| Table a mid-flight realization | `/skill:epiphany-tabling` |
+| Run an end-of-artifact checkpoint | `/skill:capturing-learnings` |
+| Create a handoff | `/skill:create-handoff` |
+| Resume a handoff | `/skill:resume-handoff <handoff-path>` |
+
+## See also
+
+- RPIV README: `@juicesharp/rpiv-pi`
+- `setup-dons-flow` — onboarding skill
+- `land` — the 10-step closeout
+- `epiphany-tabling` — scope control
+- `capturing-learnings` — promotion rule and end-of-artifact checkpoints
+- `verification-before-completion` — evidence-first discipline
+- `docs/runbooks/monitor-upstream-evolution.md` — how to track RPIV and Superpowers over time

package/skills/epiphany-tabling/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: epiphany-tabling
+description: Use when an unexpected realization, pattern, follow-up item, or fork in the road surfaces mid-task — table it to docs/tabled.md instead of derailing the current work
+---
+
+# Epiphany Tabling
+
+## Overview
+
+When something unexpected surfaces mid-work — a realization, a fork in the road, a follow-up item, a pattern we almost missed — we do not stop and redesign. We **table it**: add a short entry to `docs/tabled.md` with enough context to reconstruct later, then keep going.
+
+`docs/tabled.md` is the single working-memory location for both epiphanies and tabled follow-up work. (Per-milestone followup files were retired at M4.5 close in favor of this unified location.)
+
+**Announce at start:** "I'm using the epiphany-tabling skill to table `<topic>` — will process it at the next checkpoint."
+
+## The rule
+
+An epiphany is either:
+
+1. **Acted on immediately**, if trivially cheap and in-scope for the current task. ("Trivially cheap" means: the current task will be done at roughly the same time either way.)
+2. **Tabled**, otherwise.
+
+Never lost. Never derailing.
+
+## What tabling looks like
+
+Add a bullet to `docs/tabled.md` with:
+
+- A one-line title stating the insight.
+- A 2–4 line description with enough context to reconstruct it later: what you were doing, what you noticed, what the shape of the fix or follow-up probably is.
+- Where its next destination probably is (spec, runbook, skill, memory, retro, drop) — when known.
+
+Example:
+
+```markdown
+- **Plan drift: `parseEvent` spread ordering in `docker-runner.ts`.** Production
+  code at ~line 67–78 spreads `...obj` AFTER setting explicit `type`/`phase`/`msg`
+  fields, so malformed JSON with `obj.type !== "status"` could overwrite the typed
+  `type` field. Not blocker for M1; fix before M2 if parseEvent is touched.
+```
+
+The entry has to be reconstructable cold. Assume future-Claude has not read the current conversation — write enough that the entry stands alone.
+
+## When NOT to table
+
+- **In-scope trivial fixes.** If the fix is three lines and the current task's tests already exercise it, just do it.
+- **Clarifications the user just asked for.** Answer in conversation; don't table an answer to a live question.
+- **Things already captured elsewhere** (existing `tabled.md` entry, spec section, memory entry) — update those, don't duplicate.
+
+## Processing
+
+Tabled entries are processed at:
+
+- An **end-of-artifact checkpoint** (after an approved spec, plan, or major commit set).
+- A **milestone retro** (processed alongside keep-doing / stop-or-change).
+- A **milestone close** — outstanding items worth keeping roll into [`docs/roadmap.md#backlog`](../../docs/roadmap.md#backlog); completed/obsolete items are dropped. The file ends each milestone empty (or near-empty).
+- **Ad-hoc**, if the working file grows past a screen of content — that is a signal to process, not to let it sprawl.
+
+Each entry is processed into its probable destination (roadmap Backlog, spec amendment, runbook, skill, memory entry, as-built adaptation, or conscious drop) and then **removed** from `docs/tabled.md`. `tabled.md` stays small; entries arrive, get processed, and leave.
+
+## Related practices
+
+- `capturing-learnings` — the promotion rule that decides whether a processed entry becomes a skill, runbook, or memory.
+- `writing-retros` — the milestone-level ritual where tabled entries often land.

package/skills/finishing-a-development-branch/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: finishing-a-development-branch
+description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup
+---
+
+# Finishing a Development Branch
+
+## Overview
+
+Guide completion of development work by presenting clear options and handling chosen workflow.
+
+**Core principle:** Verify tests → Present options → Execute choice → Clean up.
+
+**Announce at start:** "I'm using the finishing-a-development-branch skill to complete this work."
+
+## The Process
+
+### Step 1: Verify Tests
+
+**Before presenting options, verify tests pass:**
+
+```bash
+# Run project's test suite
+npm test / cargo test / pytest / go test ./...
+```
+
+**If tests fail:**
+```
+Tests failing (<N> failures). Must fix before completing:
+
+[Show failures]
+
+Cannot proceed with merge/PR until tests pass.
+```
+
+Stop. Don't proceed to Step 2.
+
+**If tests pass:** Continue to Step 2.
+
+### Step 2: Determine Base Branch
+
+```bash
+# Try common base branches
+git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
+```
+
+Or ask: "This branch split from main - is that correct?"
+
+### Step 3: Present Options
+
+Present exactly these 4 options:
+
+```
+Implementation complete. What would you like to do?
+
+1. Merge back to <base-branch> locally
+2. Push and create a Pull Request
+3. Keep the branch as-is (I'll handle it later)
+4. Discard this work
+
+Which option?
+```
+
+**Don't add explanation** - keep options concise.
+
+### Step 4: Execute Choice
+
+#### Option 1: Merge Locally
+
+```bash
+# Switch to base branch
+git checkout <base-branch>
+
+# Pull latest
+git pull
+
+# Merge feature branch
+git merge <feature-branch>
+
+# Verify tests on merged result
+<test command>
+
+# If tests pass
+git branch -d <feature-branch>
+```
+
+Then: Cleanup worktree (Step 5)
+
+#### Option 2: Push and Create PR
+
+```bash
+# Push branch
+git push -u origin <feature-branch>
+
+# Create PR
+gh pr create --title "<title>" --body "$(cat <<'EOF'
+## Summary
+<2-3 bullets of what changed>
+
+## Test Plan
+- [ ] <verification steps>
+EOF
+)"
+```
+
+Then: Cleanup worktree (Step 5)
+
+#### Option 3: Keep As-Is
+
+Report: "Keeping branch <name>. Worktree preserved at <path>."
+
+**Don't cleanup worktree.**
+
+#### Option 4: Discard
+
+**Confirm first:**
+```
+This will permanently delete:
+- Branch <name>
+- All commits: <commit-list>
+- Worktree at <path>
+
+Type 'discard' to confirm.
+```
+
+Wait for exact confirmation.
+
+If confirmed:
+```bash
+git checkout <base-branch>
+git branch -D <feature-branch>
+```
+
+Then: Cleanup worktree (Step 5)
+
+### Step 5: Cleanup Worktree
+
+**For Options 1, 2, 4:**
+
+Check if in worktree:
+```bash
+git worktree list | grep $(git branch --show-current)
+```
+
+If yes:
+```bash
+git worktree remove <worktree-path>
+```
+
+**For Option 3:** Keep worktree.
+
+## Quick Reference
+
+| Option | Merge | Push | Keep Worktree | Cleanup Branch |
+|--------|-------|------|---------------|----------------|
+| 1. Merge locally | ✓ | - | - | ✓ |
+| 2. Create PR | - | ✓ | ✓ | - |
+| 3. Keep as-is | - | - | ✓ | - |
+| 4. Discard | - | - | - | ✓ (force) |
+
+## Common Mistakes
+
+**Skipping test verification**
+- **Problem:** Merge broken code, create failing PR
+- **Fix:** Always verify tests before offering options
+
+**Open-ended questions**
+- **Problem:** "What should I do next?" → ambiguous
+- **Fix:** Present exactly 4 structured options
+
+**Automatic worktree cleanup**
+- **Problem:** Remove worktree when might need it (Option 2, 3)
+- **Fix:** Only cleanup for Options 1 and 4
+
+**No confirmation for discard**
+- **Problem:** Accidentally delete work
+- **Fix:** Require typed "discard" confirmation
+
+## Red Flags
+
+**Never:**
+- Proceed with failing tests
+- Merge without verifying tests on result
+- Delete work without confirmation
+- Force-push without explicit request
+
+**Always:**
+- Verify tests before offering options
+- Present exactly 4 options
+- Get typed confirmation for Option 4
+- Clean up worktree for Options 1 & 4 only
+
+## Integration
+
+**Called by:**
+- **land** (Step 10) — cycle closeout after verification and review
+- **dons-flow** — after `/skill:implement` and `/skill:validate` complete
+
+**Pairs with:**
+- **using-git-worktrees** - Cleans up worktree created by that skill

package/skills/land/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: land
+description: Use at the end of a major piece of work to bring the cycle to a clean close — review the work, document what changed, capture lessons, and prepare for the next cycle
+---
+
+# Land
+
+Bring the current piece of work to a clean close. Review what was built, document what changed, capture lessons, and leave the codebase ready for the next cycle.
+
+## When to Use
+
+- A design phase is complete and agreed
+- An implementation plan has been fully executed and verified
+- Any significant milestone where the project state has materially changed
+- Before starting the next piece of work
+
+This is a **cycle boundary** — the moment between "we finished that" and "what's next."
+
+## When NOT to Use
+
+- Mid-work checkpoints (that's normal commit discipline)
+- Bug fixes or small refactors that don't change the project's shape
+- Session endings where the work isn't at a natural completion point (just commit and note what's unfinished)
+
+## The Process
+
+Land has 10 ordered sub-steps. **Each sub-step is a conversation between agent and human, not unilateral execution.** Surface findings or work for the step, get review, decide together when to advance. See [`docs/ways-of-working.md`](../../../docs/ways-of-working.md) §"Development Lifecycle" for the canonical descriptions.
+
+**Hard ordering rule:** all reviews (1–3) precede all documentation work (4–7). Documentation describes what is true; if a review changes what is true, doc work is wasted.
+
+### 1. Code review
+
+Comprehensive, back-and-forth review of all code that landed during this cycle. Find issues; fix small ones now, table substantive ones to `docs/tabled/`. Often a substantial conversation in itself.
+
+### 2. Architectural review
+
+Did this work introduce new patterns? Stress the architecture? Indicate that an existing pattern should change? Find structural issues — fix small ones now, table substantive ones.
+
+### 3. Security review
+
+Scope to the change. Find issues, fix small ones now, table substantive ones. (Once `docs/security-register.md` and the security-review skill exist, follow that playbook.)
+
+### 4. As-built documentation
+
+Once the code is final, capture what changed and why in `docs/changes/` (project-level) or per-repo `docs/changes/`. Use the `as-built-documentation` skill — it handles the synthesis, writing, and cleanup of superseded plans.
+
+### 5. Doc / knowledge-graph review
+
+Sweep over docs touched by this cycle. Add or refresh README files in the significant folders we worked in, per the incremental "build by touched folder" pattern (see WoW §"README knowledge graph"). Look for stale, contradictory, or low-signal docs and prune. Keep signal-to-noise high.
+
+If unsure where new information should live, consult [`docs/memory.md`](../../../docs/memory.md).
+
+### 6. AGENTS.md updates
+
+Root and repo-level. Only update what actually changed.
+
+### 7. Memory reconcile
+
+Review persistent memory (markdown files in `docs/memory/` and any auto-loaded project memory) against the new state. Correct stale entries, remove redundancies, add new feedback / project / reference / user memories warranted by the cycle. Memory is a thin index pointing at authoritative sources, not a duplication.
+
+### 8. Retro
+
+Reflect on the cycle. What went well, what was hard, patterns to capture, anti-patterns to nudge against. Produce a permanent retro doc at `docs/retros/YYYY-MM-DD-<topic>.md`. Retro **closes off the cycle's work** — process improvement, not scope. Scope changes already got captured in steps 1–3 as tabled items / memories.
+
+**Start by reading the previous retro in `docs/retros/`** — this threads the continual-improvement loop forward across cycles.
+
+### 9. Status review + tabled-items confirmation + next piece of work
+
+Walk through `docs/status.md` intentionally with the cycle's tabled items in hand. Decide what belongs in "Recently Completed," "What's Next," what to prune. **Resolve every tabled item** — either decide-now (document the decision and delete the tabled doc) or move-to-status (substance moves to "What's Next" and the tabled doc is deleted). `docs/tabled/` should end the cycle empty (just `.gitkeep`). Identify the next piece of work — usually the highest-priority moved-to-status item.
+
+### 10. Integrate
+
+If on a **feature branch**, invoke the **finishing-a-development-branch** skill to handle merge/PR/cleanup decisions.
+
+If on **main**, stage all close-out changes in appropriately grouped commits and present a summary for review. Do NOT commit unilaterally — let the human approve groupings first.
+
+## Key Principles
+
+- **Each sub-step is a conversation.** Surface findings, get review, advance together. Don't execute multiple sub-steps in a single agent turn without human checkpoints.
+- **This skill owns the sequence; child skills own the execution.** Don't duplicate instructions that live in referenced skills (`as-built-documentation`, `finishing-a-development-branch`).
+- **Documents live where their scope lives.** Repo-specific docs in the repo. Cross-repo / project-level docs at the root.
+- **Set up the next agent for success.** Every step should leave the codebase navigable: tabled items resolved, status current, retro filed, memories reconciled.
+
+## Anti-patterns
+
+- **Merge before close-out.** Don't partial-merge an in-flight branch and then try to retroactively close out a subset. Close the branch as a complete piece of work, table the continuation, pick up next on a fresh branch.
+- **Treating a sub-step as a checkbox.** Each is a conversation. Rushing produces work that needs walking back.
+- **Carrying tabled items across cycles.** Step 9 resolves every one.
+
+## Development Lifecycle Context
+
+This project uses a skills-driven development lifecycle (RPIV pipeline + Superpowers-style closeout):
+
+1. **Discover** — Interview-driven intent capture (`/skill:discover` from RPIV)
+2. **Research** — Codebase context and precedent mapping (`/skill:research` from RPIV)
+3. **Design / Blueprint** — Architecture and phased planning (`/skill:design`, `/skill:blueprint`, or `/skill:explore` from RPIV)
+4. **Plan** — Implementation plan sequencing (`/skill:plan` from RPIV, when design and plan are separate)
+5. **Implement** — Phased execution (`/skill:implement` from RPIV)
+6. **Verify** — Validation against the plan's success criteria (`/skill:validate` from RPIV, guided by `verification-before-completion` discipline)
+7. **Review / Commit** — Code review and atomic commits (`/skill:code-review` and `/skill:commit` from RPIV)
+8. **Land** — This skill. The 10 sub-steps above bring the cycle to a clean close.
+
+Not every piece of work goes through all stages. Small changes may skip brainstorming and planning. The workflow adapts to size and complexity.