feat: implement ai-assisted authoring flow and metadata generation

.agents/skills/beads/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: beads
+description: Use when tracking work in this repo with bd/beads, especially to find ready issues, create follow-up tasks, wire dependencies, or structure epics and child tasks correctly.
+---
+
+# Beads Issue Tracking
+
+Use this skill whenever work in this repository needs to be tracked or updated in `bd`.
+
+This repo uses `bd` for all task tracking. Do not create markdown TODO lists or ad hoc tracking notes when an issue should exist instead.
+
+## When To Use
+
+- starting work and needing the next unblocked issue
+- claiming an issue before implementation
+- creating follow-up work discovered during coding or review
+- sequencing tasks with blockers
+- grouping tasks under an epic
+- closing work after verification
+
+## Core Workflow
+
+1. Find ready work:
+
+```bash
+bd ready --json
+```
+
+2. Claim the issue you are taking:
+
+```bash
+bd update <id> --claim --json
+```
+
+3. Inspect details before changing the graph:
+
+```bash
+bd show <id> --json
+```
+
+4. Create newly discovered work with provenance:
+
+```bash
+bd create "Title" \
+  --description="Why this work exists, scope, acceptance" \
+  -t task \
+  -p 2 \
+  --deps discovered-from:<parent-id> \
+  --json
+```
+
+5. Add true execution blockers when order matters:
+
+```bash
+bd dep add <blocked-id> <blocker-id> --json
+```
+
+6. Close finished work:
+
+```bash
+bd close <id> --reason "Completed" --json
+```
+
+## Dependency Rules That Matter
+
+### `discovered-from` is provenance, not scheduling
+
+Use `--deps discovered-from:<id>` to show where new work came from. This is useful for traceability, but it does not express execution order.
+
+### Blocking dependencies are directional
+
+This command:
+
+```bash
+bd dep add <blocked-id> <blocker-id> --json
+```
+
+means:
+- `<blocked-id>` depends on `<blocker-id>`
+- `<blocker-id>` must finish first
+
+Equivalent shorthand:
+
+```bash
+bd dep <blocker-id> --blocks <blocked-id> --json
+```
+
+Use whichever form is clearer in the moment, but double-check the direction before pressing enter.
+
+### Epics do not block tasks
+
+`bd` will reject epic-to-task blockers. If you want a task to belong to an epic, attach it as a child:
+
+```bash
+bd update <child-id> --parent <epic-id> --json
+```
+
+Use this pattern:
+- `parent-child` for epic grouping
+- `dep add` for task sequencing
+
+### Sequence child tasks explicitly
+
+If task B should wait for task A, add a blocker even if both share the same epic:
+
+```bash
+bd dep add <task-b> <task-a> --json
+```
+
+Parentage alone does not create execution order.
+
+## Recommended Patterns
+
+### Start a new stream of work
+
+```bash
+bd create "Ship feature epic" -t epic -p 1 --json
+bd create "Implement first task" --deps discovered-from:<epic-id> -t task -p 1 --json
+bd update <task-id> --parent <epic-id> --json
+```
+
+### Add a follow-up discovered during implementation
+
+```bash
+bd create "Handle template edge case" \
+  --description="Found while implementing AI metadata support. Capture the edge case and acceptance criteria." \
+  -t task \
+  -p 2 \
+  --deps discovered-from:<current-issue> \
+  --json
+```
+
+Then decide whether it also needs to block another issue:
+
+```bash
+bd dep add <blocked-id> <new-issue-id> --json
+```
+
+### Verify your graph
+
+Use:
+
+```bash
+bd show <id> --json
+bd ready --json
+```
+
+`bd dep tree <id>` is useful for blocker chains, but it is not the best way to verify epic child membership.
+
+## Practical Lessons From This Repo
+
+- Always use `--json` for machine-readable output.
+- Prefer serial `bd` writes. Parallel reads are usually fine, but parallel writes can trigger avoidable Dolt hiccups.
+- If `bd` reports that the Dolt server auto-started but is unreachable, retry the command once and inspect [`.beads/dolt-server.log`](/Users/wise/dev/dubstack/.beads/dolt-server.log) if it repeats.
+- `nothing to commit` warnings can appear in Dolt logs during normal `bd` activity; focus on whether the requested issue change actually landed.
+- Use clear descriptions with scope, constraints, and acceptance criteria so the next agent can execute without guesswork.
+
+## Quick Reference
+
+| Intent | Command |
+|---|---|
+| Find unblocked work | `bd ready --json` |
+| Claim work | `bd update <id> --claim --json` |
+| Inspect an issue | `bd show <id> --json` |
+| Create a task | `bd create "Title" ... --json` |
+| Link discovered work | `--deps discovered-from:<id>` |
+| Make B wait on A | `bd dep add <b> <a> --json` |
+| Attach task to epic | `bd update <task> --parent <epic> --json` |
+| Close work | `bd close <id> --reason "Completed" --json` |
+
+## Common Mistakes
+
+- Creating a follow-up issue without `discovered-from`, which loses provenance.
+- Using epic parentage as if it also enforced execution order.
+- Reversing blocker direction in `bd dep add`.
+- Trying to make an epic block a task instead of attaching the task as a child.
+- Leaving an issue unclaimed while starting implementation.

.agents/skills/dub-flow-evals/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: dub-flow-evals
+description: Use when changing AI-generated branch, commit, or PR metadata for DubStack flow, or when adding new local Evalite coverage for those outputs.
+---
+
+# Dub Flow Evals
+
+Use this skill when `dub flow` metadata quality could change and you need to validate it with the local Evalite harness.
+
+## When To Use
+
+- Prompt or rubric changes in `packages/cli/src/lib/ai-metadata.ts`
+- `dub flow` behavior changes that affect generated branch names, commit messages, or PR descriptions
+- Template-preservation changes for commit or PR bodies
+- New edge cases that should become permanent eval fixtures
+
+## Quick Run
+
+```bash
+pnpm evals
+pnpm evals:watch
+pnpm evals:export
+```
+
+The first suite lives at `packages/cli/evals/dub-flow-metadata.eval.ts`.
+
+## Core Pattern
+
+Target the pure helper, not the mutating command:
+
+- evaluate `generateFlowMetadata(...)`
+- keep git mutation coverage in tests
+- keep generation quality coverage in Evalite
+
+This keeps the eval deterministic enough to debug while still exercising the exact AI path shipped by `dub flow`.
+
+## Case Design
+
+Each case should include:
+
+- `parentBranch`
+- `stagedDiff`
+- optional `commitTemplate`
+- optional `prTemplate`
+- optional unrelated-noise text for negative assertions
+
+Prefer curated diffs over giant real snapshots. Keep enough signal for the model to infer intent, but not so much noise that failures become hard to interpret.
+
+Add cases for:
+
+- new product behavior
+- template edge cases
+- regressions found in review or user reports
+- confusing diffs where the model might overfit to tests/docs instead of the feature
+
+## Scoring Pattern
+
+Use a hybrid scorer set:
+
+- deterministic contract scorers for branch format, conventional commit subject, template heading preservation, no markdown fences, and non-empty content
+- keyword/focus checks for must-mention and must-not-mention terms
+- one AI judge scorer for overall reviewer usefulness and diff fidelity
+
+Do not score exact wording. That makes the suite brittle and rewards prompt overfitting instead of better metadata.
+
+## Implementation Notes
+
+- Reuse existing DubStack AI env vars. Do not add eval-only secrets unless absolutely necessary.
+- Keep the judge prompt strict about JSON output and parse failures as low scores with metadata.
+- Prefer adding a new scorer only when a failure mode is structural. If the issue is general quality, strengthen the judge rubric or add a focused case first.
+
+## Important Nuance
+
+Do not enable `traceAISDKModel` in this repo's Evalite suite unless you verify compatibility first.
+
+The current stack uses `ai@6`, and the traced-model path caused Evalite SQLite trace persistence failures during setup. Plain AI SDK calls work for the suite today, so start there and only reintroduce tracing after confirming it stores cleanly.
+
+## Workflow
+
+1. Add or update a case in `packages/cli/evals/dub-flow-metadata.eval.ts`.
+2. Run `pnpm evals`.
+3. If the failure is structural, add or refine a deterministic scorer.
+4. If the failure is quality-related, improve the prompt/helper or judge rubric.
+5. Re-run `pnpm evals:watch` while iterating.
+6. Export a report with `pnpm evals:export` when you want a shareable artifact.
+
+## Common Mistakes
+
+- Evaluating `flow.ts` end-to-end instead of the pure helper
+- Writing exact-string assertions into eval scorers
+- Letting tests/docs noise dominate the expected intent
+- Adding new env vars for the judge when existing provider config already works
+- Treating a judge-score dip as prompt-only work when the real issue is missing structural validation

.agents/skills/dub-flow/SKILL.md

@@ -5,21 +5,23 @@ description: Use when turning staged changes into a DubStack branch, commit, and
 
 # DubStack PR Flow
 
-Use this skill when a user asks to "create a PR" or "submit this" from staged changes.
+Use this skill when a user asks to "create a PR" or "submit this" from staged changes, especially when you want the CLI path to mirror `dub flow`.
 
 ## Goal
 
 Produce a clean, reviewable stack operation with:
 1. suggested branch name
 2. suggested commit message
-3. optional issue linkage
-4. execution via `dub create` and `dub submit`
+3. suggested PR description
+4. optional issue linkage
+5. execution via `dub flow` when AI is available, or `dub create` + `dub submit` when manual mode is required
 
 ## Preconditions
 
 - Current directory is a git repo.
 - Staged changes exist (or user explicitly wants help staging).
 - `gh` auth is configured for PR operations.
+- If using AI flow, `dub config ai-assistant on` is enabled for the repo.
 
 ## Phase 1: Analyze Changes
 
@@ -75,15 +77,33 @@ If user provided issue ID (for example `A-35`), append:
 Completes A-35
 ```
 
-### PR title/body guidance
+### PR description guidance
 
-Since `dub ss` manages stack submission, focus on high-quality commit messages and branch names first. If user asks to polish PR text, prepare concise title/body recommendations after submission.
+- PR title should stay equal to the commit subject for squash-merge safety.
+- AI-generated PR text should focus on the description body only.
+- If the repo has a PR template, preserve its headings and section order.
+
+### Template-aware metadata
+
+If the repo has templates, use them as the formatting contract:
+
+- PR template locations:
+  - `.github/pull_request_template.md`
+  - `.github/PULL_REQUEST_TEMPLATE.md`
+  - `.github/PULL_REQUEST_TEMPLATE/*.md`
+  - `docs/pull_request_template.md`
+  - `pull_request_template.md`
+- Commit template:
+  - configure with `git config commit.template .gitmessage`
+
+The first line of the commit message still must be a valid Conventional Commit subject.
 
 ## Phase 3: Confirm Before Execution
 
 Present:
 - suggested branch name
 - suggested commit message
+- suggested PR description
 - what command you plan to run
 
 Ask user to choose:
@@ -93,6 +113,16 @@ Ask user to choose:
 
 ## Phase 4: Execute
 
+### Preferred AI path
+
+```bash
+dub flow --ai -a
+```
+
+- `dub flow` previews branch, commit, PR, and planned commands before mutation.
+- In non-interactive terminals, add `-y` because approval prompts require a TTY.
+- Use `dub f --dry-run` when you only need preview output.
+
 ### Default path (stage all)
 
 ```bash
@@ -125,6 +155,8 @@ dub pr
 - **No staged changes**: ask user to stage files or choose `-a/-u/-p` flow.
 - **Branch exists already**: suggest alternate name.
 - **GitHub auth errors**: prompt `gh auth login`.
+- **AI not enabled**: prompt `dub config ai-assistant on` and configure repo defaults if appropriate.
+- **Non-interactive terminal**: rerun with `-y` or use `--dry-run` if the user only wants preview output.
 - **Submit conflicts/restack issues**: run `dub restack`, resolve conflicts, then rerun `dub ss`.
 
 ## Success Output Template

.agents/skills/dubstack/SKILL.md

@@ -160,6 +160,32 @@ dub trunk
 5. Iterate with `dub m ...` and `dub ss`
 6. Keep updated with `dub sync` (add `--restack` when you want automatic post-sync rebasing)
 
+## AI Workflow
+
+```bash
+dub ai env --gemini-key "<your-key>"
+# or
+dub ai env --gateway-key "<your-key>"
+
+dub config ai-assistant on
+dub config ai-defaults create on
+dub config ai-defaults submit on
+dub config ai-defaults flow on
+```
+
+AI-assisted path:
+
+1. stage changes or use `-a`, `-u`, or `-p`
+2. run `dub flow --ai`
+3. review the rendered branch, commit, and PR previews
+4. approve or edit
+5. let DubStack create and submit
+
+Notes:
+
+- In non-interactive terminals, add `-y` because `dub flow` approval prompts require a TTY.
+- `dub ai ask` streams response text live and renders tool/status lines separately in TTY output.
+
 ## Recovery Patterns
 
 ### Restack conflict