arcane-cli 0.39.0 → 1.1.0

package/dist/assets/.arcane/spells/spell-enchant.md

@@ -0,0 +1,386 @@
+---
+name: Spell — Enchant
+description: "Enchant a PRD from functional to exceptional — proactively enhance features, UX, accessibility, security, and performance using a research lens and a marketing/brand lens"
+claude_description: Use PROACTIVELY when a PRD should be enhanced — UX, accessibility, security, performance — before implementation.
+argument-hint: "Path to PRD, pasted PRD content, or tracker work item ID (e.g., 'Enchant PRD.md for {BUSINESS_NAME} <feature> dashboard')"
+agent: agent
+---
+
+## Executive Summary
+
+- This spell takes an existing PRD and enchants it to production-grade quality.
+- It proactively identifies missing features, UX gaps, accessibility issues, performance targets, and security requirements that the original PRD didn't specify.
+- Applies two analytical lenses: a **research lens** (competitive analysis, industry standards) and a **marketing/brand lens** (brand, UX, first-impression review). In the default Arcane roster these map to the Alexander and Circe personas; other orgs map their own — see [agent-policies](../../.arcane/governance/agent-policies.md) / [naming-conventions](../../.arcane/governance/naming-conventions.md).
+- Output: Enhanced PRD with `[ENCHANTED]`-tagged additions, before/after quality scorecard, and research summaries.
+- Use this between `spell-plan` and `spell-architect` (or `spell-scope` for large PRDs). It **consumes** a drafted PRD and **feeds** an architecture/scoping spell; it does not author a PRD from scratch (that is `spell-plan`) nor implement one (`spell-implement`).
+
+---
+
+Enchant the provided PRD to exceptional quality.
+
+Use these files for context. All are optional — if a file is absent, fall back as noted and continue rather than aborting:
+
+- [governance/product-excellence-standards.md](../../.arcane/governance/product-excellence-standards.md) — Quality dimensions, PRD Quality Scorecard, scoring rubric (Bronze / Silver / Gold). **If missing:** warn the user that the canonical scorecard was not found, then proceed with the embedded dimension list (Requirements Completeness, UX, Accessibility, Performance, Security, Responsive Design, Competitive Differentiation) and default to the **Public MVP** profile.
+- [governance/development-methodology.md](../../.arcane/governance/development-methodology.md) — Spell Loop methodology, story sizing rules. **If missing:** treat story sizing as advisory and proceed.
+- [governance/testing-standards.md](../../.arcane/governance/testing-standards.md) — Testing frameworks and coverage thresholds. **If missing:** omit framework-specific coverage targets from acceptance criteria.
+- [security/threat-model.md](../../security/threat-model.md) — Active threat model. **If missing:** apply generic OWASP-style security baselines for the Security dimension.
+- [agents/agent-policies.md](../../.arcane/governance/agent-policies.md) / [governance/naming-conventions.md](../../.arcane/governance/naming-conventions.md) — Agent roster and persona naming. **If missing:** apply the two lenses (research, marketing/brand) without naming personas.
+- [DECISIONS.md](../../DECISIONS.md) — Existing ADRs to respect. **If missing:** assume no binding ADR constraints.
+- [project.md](../../project.md) — Project goals and business context. **If missing:** infer business context from the PRD itself and flag any assumptions.
+
+---
+
+## Workflow
+
+### 1. PRD Intake
+
+Accept the PRD from one of these input sources:
+
+| Source | Format | How to fetch |
+|--------|--------|--------------|
+| **File path** | `PRD.md` or any markdown file | Read the file directly |
+| **Pasted content** | Inline text in the prompt | Use as-is |
+| **Tracker work item ID** | `#508` or `508` with a tracker reference | Respect `tracking_mode` and detect the provider (see below), then fetch the work item and extract its title, description, and acceptance criteria |
+
+If the input is a tracker work item ID:
+1. **Determine tracking mode and provider.** Read `tracking_mode` (internal/external) from `.arcane.json` or PRD frontmatter, and detect the configured tracker provider rather than assuming one. The shared tracker-resolution rules live in [governance/development-methodology.md](../../.arcane/governance/development-methodology.md) — follow them rather than hard-coding a single provider.
+   - For an **Azure DevOps** provider, fetch via `az boards work-item show --id {id} --org https://dev.azure.com/{ADO_ORG} --output json` and extract `System.Description`, `Microsoft.VSTS.Common.AcceptanceCriteria`, and `System.Title`. Resolve `{ADO_ORG}` (and `{ADO_PROJECT}` if needed) from `.arcane.json` or the PRD frontmatter; **if unset, ask the user** rather than assuming a default.
+   - For other providers (e.g. a GitHub issue), use the provider's equivalent fetch and map title / body / acceptance-criteria fields accordingly.
+2. If the work item has child items, fetch those too — they may contain additional requirements.
+3. If the work item description contains a URL to an external PRD (e.g., a gist, wiki page, or shared document), fetch that content.
+4. Combine all content into a single PRD view before proceeding.
+
+Read the full PRD. Identify:
+- **Feature name** and business context
+- **Target repo** and tech stack
+- **Current requirement count** and acceptance criteria count
+- **What quality dimensions are already addressed vs missing**
+
+**Quality Profile Selection:** Ask the user which quality profile to target (see `governance/product-excellence-standards.md § Quality Profiles`):
+
+| Profile | Best For | Default? |
+|---------|----------|----------|
+| **Internal Tool** | Dashboards, CLIs, admin panels, single-user tools | |
+| **Public MVP** | First public launch, market validation, early users | ✅ Default |
+| **Production SaaS** | Revenue-generating, public-facing, scaled products | |
+| **Custom** | User picks target tier per dimension | |
+
+If the user doesn't specify, use **Public MVP**. State the selected profile before proceeding.
+
+### 2. Quality Audit (Scorecard)
+
+Score the PRD against every dimension in `governance/product-excellence-standards.md`.
+
+Use the selected quality profile's target matrix to determine the **gap** for each dimension:
+
+```markdown
+## Quality Scorecard — Before Enchantment
+
+**Profile:** [selected profile]
+
+| Dimension | Current | Target | Gap | Notes |
+|-----------|---------|--------|-----|-------|
+| Requirements Completeness | 🥉 / 🥈 / 🥇 | [from profile] | [tiers to close] | [specific gaps] |
+| User Experience (UX) | 🥉 / 🥈 / 🥇 | [from profile] | | [specific gaps] |
+| Accessibility | 🥉 / 🥈 / 🥇 | [from profile] | | [specific gaps] |
+| Performance | 🥉 / 🥈 / 🥇 | [from profile] | | [specific gaps] |
+| Security | 🥉 / 🥈 / 🥇 | [from profile] | | [specific gaps] |
+| Responsive Design | 🥉 / 🥈 / 🥇 | [from profile] | | [specific gaps] |
+| Competitive Differentiation | 🥉 / 🥈 / 🥇 | [from profile] | | [specific gaps] |
+| **Overall** | **🥉 / 🥈 / 🥇** | | | |
+```
+
+For each dimension where the current score is **below the profile's target**, identify the **specific gaps** that must be closed. These gaps drive the Must-Add tier. For dimensions already at target, identify what would lift them one tier higher (Should-Add).
+
+### 3. Research Phase (Research Lens)
+
+Apply the **research lens** (in the default Arcane roster this is the Alexander / Research & Backlog Analyst persona — see [agent-policies](../../.arcane/governance/agent-policies.md) / [naming-conventions](../../.arcane/governance/naming-conventions.md); other orgs map their own analyst). Conduct a thorough analysis:
+
+#### 3a. Competitive Analysis
+- Identify the top 3 alternatives/competitors for this type of app
+- What do they do well that this PRD doesn't specify?
+- What are their weaknesses that this app can capitalize on?
+- What features do users of these alternatives consistently request?
+
+#### 3b. Industry UX Patterns
+- What are the established UX patterns for this category of app?
+- Are there design system conventions this PRD should follow (Material, Fluent, etc.)?
+- What interaction patterns do users expect as standard?
+
+#### 3c. Accessibility Audit
+- What WCAG 2.1 AA requirements are missing from the PRD?
+- Are there accessibility features specific to this app category (e.g., data tables need row headers)?
+- What assistive technology considerations apply?
+
+#### 3d. Technology Trends
+- Are there modern approaches or frameworks that would improve the implementation?
+- Are there emerging standards the PRD should adopt early?
+- Are there performance optimization techniques specific to this stack?
+
+#### 3e. User Expectations
+- What do users of similar apps consider table-stakes features?
+- What are common frustrations with alternative apps that this PRD could address?
+- What would a power user expect that a casual user wouldn't think to request?
+
+Document findings as (the persona name below reflects the default roster; substitute your org's analyst):
+```markdown
+## Research Summary (Research Lens — default: Alexander)
+
+### Competitive Landscape
+[findings]
+
+### UX Pattern Analysis
+[findings]
+
+### Accessibility Gaps
+[findings]
+
+### Technology Recommendations
+[findings]
+
+### User Expectations
+[findings]
+```
+
+### 4. Marketing & Brand Review (Marketing/Brand Lens)
+
+Apply the **marketing/brand lens** (in the default Arcane roster this is the Circe / Marketing Strategist persona — see [agent-policies](../../.arcane/governance/agent-policies.md) / [naming-conventions](../../.arcane/governance/naming-conventions.md); other orgs map their own strategist). Evaluate the PRD from a brand and user-perception perspective:
+
+#### 4a. First Impressions
+- If a user saw this app for the first time with zero context, what would they think?
+- Is the value proposition immediately clear?
+- Does the UI convey quality and trustworthiness?
+
+#### 4b. Value Proposition Clarity
+- Can the app's purpose be explained in one sentence?
+- Does the PRD define a "signature feature" that makes the app memorable?
+- Is there a clear differentiator from alternatives?
+
+#### 4c. Brand Consistency
+- Does the planned UX align with the business's brand identity?
+- Is the tone, terminology, and visual language consistent?
+- Would this app feel like it belongs in the same family as the business's other products?
+
+#### 4d. User Onboarding
+- Is there a clear path from first launch to first value delivered?
+- Does the PRD define what "activation" means (the moment the user gets value)?
+- Are there engagement hooks that encourage return visits?
+
+#### 4e. Delight Opportunities
+- Where can the app surprise users with thoughtful touches?
+- Are there moments where exceeding expectations is easy but impactful?
+- What would make users want to recommend this app to others?
+
+Document findings as (the persona name below reflects the default roster; substitute your org's strategist):
+```markdown
+## Marketing Review (Marketing/Brand Lens — default: Circe)
+
+### First Impression Assessment
+[findings]
+
+### Value Proposition
+[findings]
+
+### Brand Alignment
+[findings]
+
+### Onboarding Path
+[findings]
+
+### Delight Opportunities
+[findings]
+```
+
+### 5. Generate Enhancement Suggestions
+
+Based on the quality audit, the research-lens analysis, the marketing/brand-lens review, **and the selected quality profile**, produce enhancement suggestions in four priority tiers.
+
+Tier assignment is driven by the profile's target matrix (see `governance/product-excellence-standards.md § How Profiles Drive Enhancement Tiers`):
+
+| Tier | Rule |
+|------|------|
+| Must-Add | Current score is **below** the profile's target for that dimension |
+| Should-Add | Current score **matches** the target; enhancement lifts one tier above |
+| Could-Add | Current score **meets or exceeds** target; enhancement is aspirational |
+| Won't-Add | Explicitly excluded regardless of profile |
+
+**Override:** Security Bronze is always Must-Add. Accessibility gaps are always at least Should-Add.
+
+#### Must-Add (Below Target — Must Close Gap)
+Enhancements required to reach the profile's target tier for each dimension. These aren't optional — the profile demands them.
+
+*Example (Public MVP): UX is Bronze but target is Gold → loading states, error states, empty states, onboarding are all Must-Add.*
+
+#### Should-Add (At Target — Stretch One Tier)
+Enhancements that lift a dimension one tier above the profile's target. Not blocking the profile's quality bar but enchanting toward the ceiling.
+
+*Example (Internal Tool): UX is Silver (matches target) → dark mode, micro-interactions become Should-Add.*
+
+#### Could-Add (Above Target — Aspirational)
+Enhancements for dimensions already meeting or exceeding the target. Premium polish that creates delight.
+
+*Example (Internal Tool): Requirements already at Silver (target) → traceability matrix, open questions tracking become Could-Add.*
+
+#### Won't-Add (Explicitly Excluded)
+Items considered but rejected, with clear rationale. This prevents future scope creep around "should we add X?"
+
+*Example: Offline mode (not applicable for real-time dashboard), multi-language support (single market for now).*
+
+For each enhancement:
+```markdown
+- **[ENCHANTED]** [Enhancement title]
+  - **Rationale:** [Why this matters — reference research or standards]
+  - **Source:** Research lens / Marketing-brand lens / Quality scorecard gap / Industry standard
+  - **Impact on scope:** Minimal / Moderate / Significant
+  - **Acceptance criteria:** [Testable criterion]
+```
+
+### 6. Scope Budget Check
+
+⚠️ **Critical guard against scope creep.**
+
+After generating all enhancements, calculate:
+- **Original PRD scope:** [N requirements, estimated M stories]
+- **Enchantd PRD scope:** [N+X requirements, estimated M+Y stories]
+- **Scope increase ratio:** [percentage or multiplier]
+
+**If enchanted scope exceeds 2× the original:**
+1. Flag this prominently to the user
+2. Force prioritization — the user must choose which enhancements to keep
+3. Recommend splitting Must-Add into the current cycle and Should-Add/Could-Add into future iterations
+4. Never silently double the project scope
+
+Present as:
+```markdown
+## Scope Impact Assessment
+
+| Metric | Original | Enchantd | Change |
+|--------|----------|----------|--------|
+| Requirements | N | N+X | +X |
+| Estimated stories | M | M+Y | +Y |
+| Scope multiplier | — | — | X.Xx |
+
+⚠️ [Warning if > 2x, or ✅ within budget if ≤ 2x]
+```
+
+### 7. Produce Enhanced PRD
+
+Generate the enchanted PRD with these characteristics:
+
+1. **All original requirements preserved** — never remove or weaken what was already specified
+2. **New requirements tagged `[ENCHANTED]`** — clearly distinguishable from original content
+3. **Enhanced acceptance criteria** — original criteria enriched with edge cases
+4. **Quality scorecard (after)** — re-scored with all enhancements included
+5. **Research and marketing summaries** — appended as reference sections
+6. **Scope impact assessment** — included for transparency
+
+Structure:
+```markdown
+# PRD: [Feature Name] — Enchantd
+
+## Enchantment Summary
+- **Quality profile:** [Internal Tool / Public MVP / Production SaaS / Custom]
+- **Original score:** [Before]
+- **Enchantd score:** [After]
+- **Enhancements added:** [count by tier]
+- **Scope impact:** [multiplier]
+
+## Problem Statement
+[Original, enhanced if needed]
+
+## Target Users
+[Original, enhanced with persona details if missing]
+
+## Requirements
+
+### Must Have
+- [Original requirement 1]
+- [Original requirement 2]
+- **[ENCHANTED]** [New must-have from enchantment]
+
+### Should Have
+- [Original should-haves]
+- **[ENCHANTED]** [New should-haves from enchantment]
+
+### Won't Have (this iteration)
+- [Original exclusions]
+- **[ENCHANTED]** [New explicit exclusions from enchantment]
+
+## User Experience Requirements
+**[ENCHANTED section if not in original]**
+- Loading states: [specification]
+- Error states: [specification]
+- Empty states: [specification]
+- Onboarding: [specification]
+
+## Accessibility Requirements
+**[ENCHANTED section if not in original]**
+- [WCAG 2.1 AA requirements per product-excellence-standards]
+
+## Performance Requirements
+**[ENCHANTED section if not in original]**
+- [Targets per product-excellence-standards]
+
+## Security Requirements
+**[ENCHANTED section if not in original]**
+- [Requirements per product-excellence-standards]
+
+## Responsive Design Requirements
+**[ENCHANTED section if not in original]**
+- [Breakpoints and adaptation rules]
+
+## Acceptance Criteria
+- [ ] [Original criteria — preserved]
+- [ ] **[ENCHANTED]** [New criteria from enchantment]
+
+## Dependencies
+[Original + any new dependencies from enchanted requirements]
+
+## Open Questions
+[Original + any new questions raised by enchantment]
+
+## Quality Scorecard
+
+| Dimension | Before | After |
+|-----------|--------|-------|
+| Requirements | 🥉 | 🥇 |
+| UX | 🥉 | 🥇 |
+| ... | ... | ... |
+| **Overall** | **🥉** | **🥇** |
+
+## Research Summary (Research Lens — default: Alexander)
+[Condensed from Step 3]
+
+## Marketing Review (Marketing/Brand Lens — default: Circe)
+[Condensed from Step 4]
+```
+
+### 8. Present for Review
+
+Present the enchanted PRD to the user with:
+
+1. **Side-by-side quality score** — before and after across all dimensions
+2. **Summary of all additions** — grouped by tier (Must-Add / Should-Add / Could-Add / Won't-Add) with rationale
+3. **Scope impact** — clear multiplier and warning if > 2×
+4. **Explicit ask:** "Do you want to proceed with the enchanted PRD, adjust any enhancements, or revert to the original?"
+
+Wait for user approval before the enchanted PRD replaces the original. The user may:
+- **Accept all** — proceed with the full enchanted PRD
+- **Accept with cuts** — remove specific enhancements; re-run scorecard
+- **Defer enhancements** — keep the original PRD for this cycle; log enhancements as future work items
+- **Reject** — keep the original PRD unchanged
+
+---
+
+## Rules
+
+- **Never remove or weaken original requirements.** Only enhance and add. The user wrote those requirements for a reason.
+- **Every enhancement must have a rationale** tied to research findings, competitive analysis, industry standards, or the quality scorecard. No enhancements "because it would be nice."
+- **User has final say on all additions.** This spell is a suggestions engine, not a mandate. If the user says "no dark mode," respect that.
+- **Flag scope impact honestly.** If enhancements double the project, say so clearly. Don't bury scope creep in a long list.
+- **Respect existing ADRs.** If an enhancement contradicts an established ADR, flag the conflict rather than silently adding it.
+- **Be honest about unknowns.** If competitive analysis requires actual market research that can't be done in this context, flag it as a research item for the research lens (default: Alexander) to investigate separately.
+- **Don't gold-plate for the sake of it.** If the PRD already meets the profile's targets across all dimensions, say so and move on. Not every PRD needs enchantment.
+- **Respect the quality profile.** The profile determines what's Must-Add vs Could-Add. An Internal Tool doesn't need Gold Accessibility unless the user says so. A Production SaaS needs Gold everywhere — no shortcuts.
+- **Security enhancement is non-negotiable.** Even if the user skips other enhancements, security gaps identified during enchantment must be flagged prominently. The user can still decide, but they must be aware. Security Bronze is always Must-Add regardless of profile.
+- **Accessibility is a requirement, not a feature.** Accessibility gaps are always at least Should-Add regardless of profile. WCAG 2.1 AA compliance should be treated as Must-Add for Public MVP and Production SaaS profiles.

package/dist/assets/.arcane/spells/spell-explain-concept.md

@@ -0,0 +1,70 @@
+---
+name: Spell — Explain Concept
+description: "Explain a technical concept, architecture, or system behavior in a balanced way: enough technical depth to be accurate, enough plain language to be accessible. Use when: confused about how something works, need to understand a system before making decisions, want a 'teach me' breakdown."
+claude_description: Use PROACTIVELY when the user needs a concept, architecture, or system behavior explained before deciding or building.
+argument-hint: "Concept or question to explain (e.g., 'how does our auth middleware inject tokens?', 'what is OAuth2 PKCE flow?', 'why can't {AGENT_NAME} see the config?')"
+agent: agent
+---
+
+## Executive Summary
+
+- This prompt produces clear, structured explanations of technical concepts, architectures, or system behaviors.
+- It balances technical accuracy with accessibility — no dumbing down, no jargon walls.
+- Use this when you need to understand something before making a decision or planning implementation.
+
+---
+
+Explain the concept, system, or behavior described in the user's prompt argument.
+
+## Explanation Style
+
+Follow these rules strictly:
+
+1. **Start with the one-sentence answer.** What is it, or why does it happen? No preamble.
+2. **Use analogies from the user's world** — relate to tools, systems, or workflows they already use (their editor, their chat/notification tooling, their own agents, their own infrastructure). Check the workspace for context about the user's setup.
+3. **Use diagrams per rule 8** (`.arcane/governance/universal-agent-rules.md`) — Mermaid sequence diagrams for flows, flowcharts for decision trees. Don't use diagrams for simple definitions.
+4. **Show the "so what?"** — connect the explanation to what the user can *do* with this knowledge. What decisions does it unlock? What options does it create?
+5. **Name the moving parts** with a summary table when there are multiple components, layers, or options to compare.
+6. **Use real examples from their system** — reference actual agent names, actual config files, actual commands. Don't use generic placeholders when specific is available.
+7. **Flag when your explanation hits a boundary** — if something requires verification, testing, or is based on source code reading vs official docs, say so.
+
+## Tone Calibration
+
+- Technical jargon: **Use it, but define it inline** on first use. Example: "the dispatcher (the runtime component that routes a request to the right handler)..."
+- Depth: **Go deep enough that the user could explain it to someone else.** If they asked "what is X?", they should walk away knowing what X is, how X works, and when X matters.
+- Length: **Match the concept's complexity.** A simple definition gets 3-4 lines. An architecture explanation gets diagrams, tables, and flow breakdowns.
+
+## Research First
+
+Before explaining:
+1. Search the workspace for relevant docs, configs, and journal entries about the topic
+2. If the concept involves a specific tool or framework, check its config files, source, and official docs as needed
+3. If the concept involves infrastructure or deployment, check the relevant infra, config, and ops directories in the repo
+4. Ground the explanation in what's actually deployed, not hypothetical setups
+
+## Output Structure
+
+Adapt the structure to the concept — don't force every explanation into the same template. But generally:
+
+- **One-line answer** (always)
+- **How it works** (always — the core explanation)
+- **Diagram** (when architecture/flow matters)
+- **Comparison table** (when there are alternatives or multiple components)
+- **What this means for you** (always — connect to decisions or actions)
+
+## Rules
+
+1. **Validate the input is a concept to explain, not a task to perform.** This spell *explains* — it does not build, fix, plan, or change anything. If the argument is empty or too vague to identify a topic (e.g. "explain this" with no referent), ask the user what they want explained before proceeding.
+2. **Redirect action requests.** If the argument is actually a request to *do* work rather than understand it, say so and point to the right spell instead of attempting the action:
+   - "implement / build / add X" → suggest **`spell-implement`**.
+   - "fix / debug X" → suggest **`spell-bug`**.
+   - "plan / break down X" → suggest **`spell-plan`**.
+   - "design / decide between X and Y (architecture)" → suggest **`spell-architect`**.
+   - If the user genuinely wants *both* an explanation and then action, explain first, then hand off.
+3. **Explain only — never modify.** Do not edit files, run mutating commands, or make external posts as part of an explanation. Reading and searching the workspace is expected; changing it is out of scope.
+
+## Related Spells
+
+- **`spell-architect`** — when the concept is a *design choice* and the user needs a decision (trade-offs, ADR), explain the landscape here, then hand off to architect to decide.
+- **`spell-plan`** — once a concept is understood, plan turns that understanding into ordered, actionable steps.
+- **`spell-implement`** / **`spell-bug`** — the build/fix spells this one redirects to when the request is an action rather than a question.

package/dist/assets/.arcane/spells/spell-feedback.md

@@ -0,0 +1,138 @@
+---
+name: Spell — Feedback
+description: Collect structured feedback on AI-assistance quality and workflow friction, and append it to FEEDBACK.md for continuous improvement. Framework-shaped items can route upstream to arcane's public GitHub issues.
+claude_description: Use PROACTIVELY when the user reports friction with AI assistance or the workflow itself, not the product being built.
+argument-hint: Optional focus area — e.g., "spell-implement loop", "review quality", "session handoff". Use `--flush` instead to re-offer any previously queued upstream items.
+agent: agent
+---
+
+## Executive Summary
+
+- This spell captures post-session feedback on how well the spells and AI assistance worked.
+- It structures the feedback into actionable improvement items and appends them to `FEEDBACK.md` at the repo root.
+- Use it after any session where assistance felt notably effective or notably off — the record feeds `spell-enchant`.
+- **Framework-shaped items** (about a spell, template, governance doc, playbook, or CLI behavior — not this repo's own content) can additionally route upstream as a GitHub issue on `{ARCANE_UPSTREAM_REPO}` — the same public intake path any arcane user would use, genericized first and gated by an explicit disclosure confirm. This is the whole consumer→arcane feedback loop: arcane is the one thing every consumer repo may reference without violating sibling isolation, because it's the installed, publicly-homed dependency, not a sibling venture.
+
+---
+
+Collect and record feedback to improve the Arcane workflow.
+
+## Flush Mode (`--flush`)
+
+If the argument is `--flush`, skip Steps 1–5 entirely. Scan `FEEDBACK.md` for improvement items marked `<!-- upstream: queued -->`, and for each one run Step 6's filing flow (genericize, confirm, file or re-queue) without re-collecting feedback. Report how many were filed, re-queued, and how many remain.
+
+The user's input describes what to give feedback on. If no argument is provided, ask one question: _"What part of the workflow or AI assistance do you want to give feedback on?"_ and wait.
+
+## Step 1 — Identify Scope
+
+From the input and recent context, determine:
+
+- **Target** — which spell, agent, or general experience is being rated.
+- **Session context** — the recent task/feature (check `TODO.md`, `DECISIONS.md`, latest `journal/` entry).
+- **Type** — output quality, workflow friction, or tooling/setup.
+
+Do not ask for anything you can infer from the conversation.
+
+## Step 2 — Prompt for Structured Feedback
+
+Ask all of this at once (not one at a time):
+
+```
+## Feedback Form
+
+**Target:** [spell/agent/experience]
+**Session:** [topic or "general"]
+
+1. Overall quality (1–5): how effective was the assistance?
+2. Friction points: what slowed you down or felt wrong?
+3. What worked well: what should stay exactly as-is?
+4. Suggested improvement: the single change that would help most?
+5. Would you use this again? (yes / yes-with-changes / no)
+```
+
+If the user already covered some fields in their input, skip those and confirm what you inferred.
+
+## Step 3 — Synthesize
+
+Extract:
+
+- **Improvement items** — specific, imperative, with a clear done-state ("Add…", "Fix…", "Remove…").
+- **Positive signals** — patterns to preserve.
+- **Blockers** — anything that prevented task completion (surface these under Friction Points).
+
+Mark an item **substantial** (TODO-worthy) if any apply: it requires editing a spell/governance/agent file, it blocked task completion, or it recurs across sessions. Trivial one-off nits stay in `FEEDBACK.md` only.
+
+For each substantial item, additionally classify **framework-shaped** vs **repo-local**: framework-shaped means the fix belongs in arcane itself (a spell prompt, template, governance doc, playbook, or CLI behavior this repo installed rather than authored); repo-local means it's specific to this repo's own content or configuration. Only framework-shaped items are offered upstream routing in Step 6.
+
+## Step 4 — Show Proposal
+
+```
+## Feedback Summary
+
+**Target:** [...]   **Date:** [YYYY-MM-DD]   **Rating:** [N/5]   **Would use again:** [yes / yes-with-changes / no]
+
+**Friction:** [...]
+**Worked well:** [...]
+**Improvement items:**
+- [ ] [item] [SUBSTANTIAL if TODO-worthy] [FRAMEWORK-SHAPED if upstream-eligible]
+
+Append to FEEDBACK.md? (yes / edit / skip)
+```
+
+If the rating is ≤ 2, prepend a `⚠️ LOW RATING` line to this proposal so it is visible before the append decision — do not bury it.
+
+## Step 5 — Apply (after approval)
+
+1. Read `FEEDBACK.md` at the repo root (create with a `# Feedback Log` header if missing).
+2. **Append** this block — never overwrite existing entries:
+
+```markdown
+---
+
+## Feedback — [Target] ([YYYY-MM-DD])
+
+**Session:** [topic or "general"]
+**Rating:** [N/5]   **Would use again:** [yes / yes-with-changes / no]
+**Submitted by:** [git config user.name if available, else "developer"]
+
+### Friction Points
+- [point — include any blockers]
+
+### What Worked
+- [strength]
+
+### Improvement Items
+- [ ] [item]
+
+### Raw Notes
+> [verbatim user input if useful]
+```
+
+3. For each item marked **substantial** in Step 3, offer to add it to `TODO.md` as a `[feedback]`-tagged item. If the user accepts, hand off to [`spell-todo`](spell-todo.md) rather than editing `TODO.md` directly — it picks the right section and avoids duplicates.
+4. For each item additionally marked **framework-shaped**, run Step 6.
+5. Do NOT commit — leave that to `spell-commit-work`.
+6. Confirm what was appended and where, then point the user to [`spell-enchant`](spell-enchant.md) if the feedback suggests a spell or PRD is ready to be lifted to the next quality tier.
+
+## Step 6 — Upstream Routing (Framework-Shaped Items)
+
+`{ARCANE_UPSTREAM_REPO}` is this install's own arcane framework repository (`owner/repo`) — resolve it from the installed `arcane-cli` package's `repository` field (e.g. `node_modules/arcane-cli/package.json`, or `npm view arcane-cli repository.url` if not vendored locally); ask the user if it cannot be determined. Never hardcode a specific org/repo here — a fork or downstream rename changes this value.
+
+For each framework-shaped item:
+
+1. **Genericize.** Strip anything identifying this specific consumer: venture/business names, org tokens, machine names, hub or local paths. Write "a consumer repo session" instead of naming the actual venture, generalize file paths to their relative form. The finding must read the same whether it came from this repo or any other arcane user's.
+2. **Check `gh`.** If unauthenticated or offline, skip straight to the fallback below.
+3. **Disclosure confirm.** Print the exact issue title and body that will be filed publicly on `{ARCANE_UPSTREAM_REPO}`, and ask for the literal word `disclose` — same discipline as `spell-manifest`'s disclosure gate; this is the same kind of act (private observation → public issue). Anything else is a decline, not an error.
+4. **File.** On `disclose`: `gh issue create --repo {ARCANE_UPSTREAM_REPO} --title "<title>" --body "<genericized body>"`. Report the issue URL.
+5. **Fallback.** If `gh` is unavailable, offline, or the operator declines: append `<!-- upstream: queued -->` to that item's line in `FEEDBACK.md`. Never block the rest of the session on this — queuing is a complete, valid outcome. The next `spell-feedback` run (or `spell-feedback --flush`) re-offers every queued item.
+
+Maintainer side is unchanged: GitHub issues are arcane's normal public intake; triage into arcane's own `IDEAS.md`/`DECISIONS.md` happens in arcane sessions like any other issue. This spell never writes to a hub's venture books and never reads `ventures/registry.json` — framework feedback and venture ideas are different channels on purpose (venture ideas → hub books → `spell-manifest`; framework lessons → here → arcane's GitHub).
+
+## Rules
+
+- Never overwrite existing feedback — always append.
+- Keep improvement items specific and actionable — no vague "improve quality".
+- If overall quality is ≤ 2, flag it with `⚠️ LOW RATING` in the Step 4 proposal (before the append decision) and offer `spell-todo` to capture a concrete fix.
+- After approval, write immediately — no further questions.
+- Never include secrets or tokens.
+- Never file an upstream issue without the literal `disclose` confirmation on that exact entry — batch approval of the local `FEEDBACK.md` append does not extend to Step 6.
+- Never write a venture name, hub path, or machine name into an upstream issue — genericize before showing the disclosure confirm, not after.