haiku-method 2.2.0

package/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "haiku-method",
+	"version": "2.2.0",
+	"description": "H·AI·K·U methodology — universal lifecycle orchestration with hat-based workflows, completion criteria, and automatic context preservation.",
+	"homepage": "https://haikumethod.ai",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/gigsmart/haiku-method.git",
+		"directory": "plugin"
+	},
+	"license": "Apache-2.0",
+	"author": {
+		"name": "GigSmart",
+		"url": "https://gigsmart.com"
+	},
+	"keywords": [
+		"haiku",
+		"haiku-method",
+		"claude-code",
+		"claude-code-plugin",
+		"lifecycle",
+		"orchestration",
+		"methodology",
+		"workflow",
+		"iteration",
+		"completion-criteria",
+		"hat-switching",
+		"context-preservation",
+		"human-ai-collaboration"
+	],
+	"files": [
+		".claude-plugin",
+		".mcp.json",
+		"bin",
+		"data",
+		"harnesses",
+		"hooks",
+		"lib",
+		"passes",
+		"providers",
+		"schemas",
+		"skills",
+		"studios",
+		"VALIDATION.md",
+		"CHANGELOG.md"
+	],
+	"publishConfig": {
+		"access": "public"
+	}
+}

package/passes/design.md

@@ -0,0 +1,29 @@
+---
+name: design
+description: Visual and interaction design
+available_workflows: [design]
+default_workflow: design
+---
+
+# Design Pass
+
+Orient all work toward design artifacts: mockups, prototypes, design tokens, and component specs. Production code is out of scope for this pass.
+
+## Builder Focus
+
+- Produce wireframes, mockups, or high-fidelity prototypes depending on the unit's fidelity requirements
+- Define or extend design tokens (colors, spacing, typography, elevation) in the project's token system
+- Specify component structure, states, and interaction behavior
+- Document responsive breakpoints and adaptive layout rules
+- Capture micro-interactions and transition specifications
+
+## Reviewer Focus
+
+- Verify designs address every acceptance criterion in the unit
+- Check consistency with existing design system tokens and patterns
+- Confirm interaction flows cover error states, empty states, and loading states
+- Ensure accessibility considerations are documented (contrast, focus order, ARIA semantics)
+
+## Completion Signal
+
+The design pass is complete when design artifacts are reviewed and detailed enough to inform subsequent product or dev passes without ambiguity. No production code is produced.

package/passes/dev.md

@@ -0,0 +1,30 @@
+---
+name: dev
+description: Working implementation
+available_workflows: [default, tdd, adversarial, bdd]
+default_workflow: default
+---
+
+# Dev Pass
+
+Orient all work toward tested, deployable code. Use design and product artifacts from prior passes as source-of-truth inputs.
+
+## Builder Focus
+
+- Implement production code that satisfies behavioral specs and acceptance criteria
+- Write tests that verify every acceptance criterion programmatically
+- Follow design specs for UI components, tokens, and interaction behavior
+- Ensure all quality gates pass (lint, type-check, test suite)
+- Keep commits small, focused, and independently verifiable
+
+## Reviewer Focus
+
+- Verify implementation matches behavioral specs from the product pass
+- Confirm UI implementation matches design artifacts from the design pass
+- Check test coverage against acceptance criteria
+- Validate that quality gates pass without suppression or workarounds
+- Review for security, performance, and maintainability concerns
+
+## Completion Signal
+
+The dev pass is complete when all acceptance criteria have passing tests, quality gates are green, and the implementation is ready for integration. All criteria must be programmatically verifiable.

package/passes/product.md

@@ -0,0 +1,30 @@
+---
+name: product
+description: Behavioral specification and gap analysis
+available_workflows: [default, bdd]
+default_workflow: default
+---
+
+# Product Pass
+
+Orient all work toward behavioral specifications, acceptance criteria, and edge case analysis. Use design artifacts from prior passes when available.
+
+## Builder Focus
+
+- Write detailed behavioral specs that describe what the system does, not how it is built
+- Define acceptance criteria for every user-facing scenario
+- Identify edge cases, error paths, and boundary conditions
+- Reference design artifacts (mockups, component specs) produced in earlier passes
+- Specify data contracts, validation rules, and state transitions
+- Document integration points and external dependency behavior
+
+## Reviewer Focus
+
+- Verify specs are precise enough for a developer to implement without follow-up questions
+- Check that edge cases and error scenarios are explicitly covered
+- Confirm behavioral specs align with design artifacts where they exist
+- Ensure acceptance criteria are testable and unambiguous
+
+## Completion Signal
+
+The product pass is complete when behavioral specifications are detailed enough for dev implementation. Every acceptance criterion must be specific and verifiable.

package/providers/comms.md

@@ -0,0 +1,75 @@
+---
+category: comms
+description: Bidirectional comms provider — notifications out, signals in
+---
+
+# Comms Provider — Default Instructions
+
+## Inbound: Provider → H·AI·K·U
+
+### Event Discovery (Session Start)
+- Check channels for messages that reference active intents
+- Surface: stakeholder feedback, approval responses, blockers raised by team members
+- Check for responses to `await` gate notifications (e.g., "customer replied")
+
+### Translation (Provider → H·AI·K·U)
+
+| Provider Concept | H·AI·K·U Concept | Translation |
+|---|---|---|
+| Channel message mentioning intent | Context for current stage | Distill relevant information |
+| Thread reply to gate notification | Gate resolution signal | Surface as "event occurred" for await gates |
+| Stakeholder feedback on shared output | Review input | Include in adversarial review context |
+
+**Key principle:** Comms channels are noisy. Claude filters for messages relevant to active intents, not everything in the channel.
+
+## Outbound: H·AI·K·U → Provider
+
+### When to Post
+- Intent elaboration complete → summary + link to epic
+- Stage gate reached → gate type determines message:
+  - `ask`: "Stage X complete, awaiting your approval"
+  - `external`: "PR created for stage X review"
+  - `await`: "Stage X complete, waiting for {event}. Reply here when it occurs."
+- Unit review approved or rejected → brief outcome
+- All stages complete → intent done notification
+- Blocking issues requiring human attention
+
+### Translation (H·AI·K·U → Provider)
+
+| H·AI·K·U Concept | Provider Concept | Translation |
+|---|---|---|
+| Stage completion summary | Channel message | Concise summary with link to artifacts |
+| Gate notification | Threaded message | Actionable request with clear next step |
+| Blocker | Urgent message / mention | Tag responsible person with blocker details |
+| Intent completion | Channel message | Summary of outcomes, link to reflection |
+
+**Key principle:** Messages should be actionable and concise. Don't dump H·AI·K·U state — tell the person what they need to do and where to find details.
+
+## Sync: Gate Resolution via Comms
+
+The comms provider can post gate notifications and receive replies, but the agent cannot use comms MCP tools to self-approve a gate. Gate advancement is controlled by the orchestrator through structural signals (branch merge detection, URL-based CLI probing), not by agent self-confirmation.
+
+For `await` gates where a comms signal is the expected resolution (e.g., a customer reply in a Slack thread), the flow is:
+
+```
+1. Stage completes → post "Waiting for {event}" to channel
+2. User replies "customer responded" or reacts with ✅
+3. User runs /haiku:pickup after the event occurs
+4. Orchestrator checks gate status and advances
+```
+
+For `await` gates where the user wants to approve locally after confirming the event occurred, the stage must have a compound gate `[await, ask]` — the `ask` component allows local approval through the review UI.
+
+### Comms as Notification, Not Signal Source
+
+Comms MCP tools (Slack, Teams, Discord) are used for:
+
+- **Outbound notifications** — posting gate status, intent completion, blockers
+- **Inbound context** — surfacing stakeholder feedback, thread replies relevant to active intents
+
+They are NOT used for gate advancement. The agent cannot confirm its own gate — that would be a process bypass.
+
+## Provider Config
+
+Provider-specific configuration lives under `providers.comms.config` in `.haiku/settings.yml`.
+Schema: `${CLAUDE_PLUGIN_ROOT}/schemas/providers/{type}.schema.json`

package/providers/crm.md

@@ -0,0 +1,95 @@
+---
+category: crm
+description: Bidirectional CRM provider — sync deals, contacts, and lifecycle state between H·AI·K·U and CRM platforms
+---
+
+# CRM Provider — Default Instructions
+
+## Inbound: Provider → H·AI·K·U
+
+### Intent Discovery (Session Start)
+- Query CRM for deals/opportunities in stages that map to H·AI·K·U work
+- Surface deals that need action: new deals to qualify, proposals to send, contracts to review
+- Check for deal stage changes that should trigger intent creation or stage advancement
+
+### Intent Seeding
+- When a new deal is discovered (or a trigger fires), distill CRM data into an intent:
+  - Deal name → intent title
+  - Deal stage → active H·AI·K·U stage (mapped via translation table)
+  - Contact information → intent context
+  - Deal amount, timeline, requirements → completion criteria context
+  - Related activities (emails, meetings, notes) → stage input context
+
+### Translation (Provider → H·AI·K·U)
+
+The CRM's data model is fundamentally different from H·AI·K·U's. Claude bridges:
+
+| CRM Concept | H·AI·K·U Concept | Translation |
+|---|---|---|
+| Deal / Opportunity | Intent | Title, description, context from deal fields |
+| Deal Stage (Prospecting, Qualification, etc.) | Active stage in sales studio | Map CRM stages to H·AI·K·U stages (see mapping below) |
+| Contact / Company | Intent context | Distill into context: who, what they need, decision makers |
+| Activities (emails, calls, meetings) | Stage input context | Summarize relevant interactions for the current stage |
+| Deal properties (amount, close date, probability) | Intent metadata | Informational context, not enforced fields |
+| Custom fields | (varies) | Include relevant custom fields in context |
+
+### Stage Mapping
+
+CRM deal stages don't map 1:1 to H·AI·K·U stages. Claude uses semantic understanding:
+
+```
+CRM: Prospecting     → H·AI·K·U: research
+CRM: Qualification   → H·AI·K·U: qualification
+CRM: Needs Analysis  → H·AI·K·U: qualification (still gathering)
+CRM: Proposal        → H·AI·K·U: proposal
+CRM: Negotiation     → H·AI·K·U: negotiation
+CRM: Closed Won      → H·AI·K·U: close (completed)
+CRM: Closed Lost     → H·AI·K·U: close (completed, outcome: lost)
+```
+
+**Key principle:** The CRM doesn't store H·AI·K·U frontmatter. Claude reads the CRM's native fields and produces H·AI·K·U artifacts. If the CRM has a "Next Steps" field, that becomes context for the current stage — not a frontmatter field.
+
+## Outbound: H·AI·K·U → Provider
+
+### State Sync (During Execution)
+- **Stage advances** → Update CRM deal stage to the mapped value
+- **Intent completes** → Mark deal as Closed Won/Lost based on outcome
+- **Key outputs produced** → Log as CRM activity (proposal sent, contract drafted)
+- **Await gate reached** → Add CRM task for the awaited action
+- **Blocker encountered** → Add CRM note with blocker details
+
+### Translation (H·AI·K·U → Provider)
+
+| H·AI·K·U Concept | CRM Concept | Translation |
+|---|---|---|
+| Stage completion | Deal stage change | Map H·AI·K·U stage to CRM stage |
+| Unit output (proposal doc, contract) | Activity / attachment | Log as activity, attach document |
+| Await gate | Task / reminder | Create CRM task: "Follow up: {awaited event}" |
+| Reflection insights | Deal notes | Summarize learnings as deal notes |
+| Intent completion | Deal close | Set outcome, amount, close date |
+
+**Key principle:** Push the minimum needed to keep the CRM accurate. Don't try to replicate H·AI·K·U's internal structure in CRM fields. A stage completion becomes a deal stage change. A reflection becomes a note. The CRM audience doesn't need to know about bolts, hats, or review agents.
+
+## Sync: Cross-Studio Triggers
+
+The CRM is a natural trigger source for cross-studio work:
+
+```
+CRM deal closes (Closed Won)
+  → Next session: Claude checks CRM, sees closed deal
+  → Suggests: "Deal Acme Corp closed. Create customer success onboarding intent?"
+  → If approved: seeds CS intent with deal context from CRM
+```
+
+This is pull-based — Claude checks the CRM at session start, not via webhooks.
+
+## Provider Config
+
+Provider-specific configuration lives under `providers.crm.config` in `.haiku/settings.yml`.
+Schema: `${CLAUDE_PLUGIN_ROOT}/schemas/providers/{type}.schema.json`
+
+Config fields:
+- `pipeline_id` — which CRM pipeline to monitor
+- `stage_mapping` — custom CRM stage → H·AI·K·U stage mapping
+- `sync_activities` — whether to log H·AI·K·U actions as CRM activities
+- `trigger_on_stage` — which CRM stage transitions should surface as intent suggestions

package/providers/design.md

@@ -0,0 +1,120 @@
+---
+name: Design Provider
+category: design
+description: Bidirectional design provider — sync design artifacts and tokens between H·AI·K·U and design tools
+supported_types:
+  - canva
+  - openpencil
+  - pencil
+  - penpot
+  - excalidraw
+  - figma
+default_type: auto
+---
+
+# Design Provider — Default Instructions
+
+## Inbound: Provider → H·AI·K·U
+
+### During Elaboration
+- Pull existing designs, components, and mockups relevant to the intent
+- Reference design files in unit Technical Specification sections
+- When generating wireframes, reference component names from the design system in HTML comments but maintain low-fidelity aesthetic
+- Extract design tokens (colors, spacing, typography) as constraints for implementation
+
+### During Stage Decomposition
+- Pull current design state for stages that consume design outputs
+- Verify designs haven't changed since the design stage completed
+
+### Translation (Provider → H·AI·K·U)
+- Design files → `design_ref` URIs in unit references
+- Design tokens → implementation constraints
+- Component inventory → scope boundary for units
+
+## Outbound: H·AI·K·U → Provider
+
+### During Design Stage
+- Push wireframes and design decisions to the design tool
+- Update component libraries with new patterns
+
+### During Development Stage
+- Push implemented component screenshots for visual diff
+- Update design tool with implementation-driven adjustments
+
+### During Review
+- Cross-reference UI implementation against design specs
+- Push review findings that affect design back to the design tool
+
+## Provider-Specific Instructions
+
+### Canva
+
+**Design creation:** Use the Canva MCP tools to create designs. Leverage brand kits (`brand_kit_id`) for consistent styling. Organize new designs into the configured `default_folder`.
+
+**Editing:** Start an editing transaction, perform batch operations, then commit. Use `start-editing-transaction` → `perform-editing-operations` → `commit-editing-transaction` workflow. Never leave transactions uncommitted.
+
+**Token/variable access:** Access brand colors, fonts, and logos through the Brand Kit API (`list-brand-kits`, `get-assets`). Map design tokens from the brand kit to implementation variables.
+
+**Export:** Export using the configured `export_format` (default: png). Use `export-design` with the appropriate format. For multi-page designs, export individual pages as needed.
+
+**design_ref storage:** Store as `canva://<design_id>` — the design ID from Canva's API. Include page references as `canva://<design_id>#page=<n>` when referencing specific pages.
+
+### OpenPencil
+
+**Design creation:** Use the OpenPencil MCP tools to create designs. Start with `design_skeleton` for layout structure, then populate with `design_content`. Use `design_refine` for iterative improvements.
+
+**Editing:** Modify designs through `update_node`, `replace_node`, and `insert_node` operations. Use `batch_design` for multiple changes in a single operation. Retrieve current state with `get_design_md` before making changes.
+
+**Token/variable access:** Use `get_variables` to read design tokens and `set_variables` to update them. Variables cover colors, spacing, typography, and component-level tokens. Apply theme presets with `load_theme_preset`.
+
+**Export:** Export to the configured `default_export_target` framework (default: react). Use `export_nodes` to export specific components or `export_design_md` for the full design as markdown. Supports 8 framework targets.
+
+**design_ref storage:** Store as `openpencil://<document_id>` — the document identifier from the OpenPencil instance. Reference specific nodes as `openpencil://<document_id>#node=<node_id>`.
+
+### Pencil
+
+**Design creation:** Use the Pencil MCP tools to create designs. Start with `batch_design` for efficient multi-element creation. Use `get_guidelines` to understand the design system constraints before creating.
+
+**Editing:** Modify elements through `replace_all_matching_properties` for bulk style changes or `batch_design` for structural changes. Use `search_all_unique_properties` to discover existing patterns before editing. Always `get_editor_state` first to understand current canvas state.
+
+**Token/variable access:** Use `get_variables` to read design tokens and `set_variables` to update them. Reference the guidelines (`get_guidelines`) for the design system's token definitions.
+
+**Export:** Export components with `export_nodes`. Use `get_screenshot` for quick visual verification during development. Export targets are determined by the implementation stack.
+
+**design_ref storage:** Store as `pencil://<document_id>` — the document identifier from the Pencil instance. Reference specific elements as `pencil://<document_id>#node=<node_id>`.
+
+### Penpot
+
+**Design creation:** Use the Penpot MCP tools via the configured `instance_url`. Create designs within the specified `project_id`. Penpot supports components, design tokens, and collaborative editing natively.
+
+**Editing:** Access the Penpot API through the MCP server on the configured `mcp_port` (default: 4401). Modify designs using Penpot's component and layer structure. Leverage Penpot's built-in version history for change tracking.
+
+**Token/variable access:** Access Penpot's design tokens through the library system. Penpot supports color, typography, and component libraries at the project level. Sync tokens between Penpot libraries and implementation variables.
+
+**Export:** Export assets through Penpot's export API. Supports SVG, PNG, and PDF formats. Export individual components or full pages. Use SVG for scalable assets, PNG for rasterized previews.
+
+**design_ref storage:** Store as `penpot://<instance_host>/<project_id>/<file_id>` — includes the instance host for multi-instance support. Reference specific components as `penpot://<instance_host>/<project_id>/<file_id>#component=<id>`.
+
+### Excalidraw
+
+**Design creation:** Use the Excalidraw MCP tools in the configured `mcp_mode` (default: remote). Apply the configured `style` (default: hand-drawn) for consistent aesthetics. Excalidraw excels at quick diagrams, architecture sketches, and low-fidelity wireframes.
+
+**Editing:** Modify drawings through the Excalidraw API. Elements are JSON-based and support direct manipulation. Use Excalidraw's grouping and frame features to organize complex drawings.
+
+**Token/variable access:** Excalidraw uses a simplified token model — primarily stroke colors, fill colors, font families, and stroke widths. Map project design tokens to Excalidraw's style properties. Use the style preset (hand-drawn/architect/artist/cartoonist) as the base.
+
+**Export:** Export as SVG for vector output or PNG for rasterized output. Excalidraw's native format (.excalidraw) is JSON and can be version-controlled directly. Export with background or transparent as needed.
+
+**design_ref storage:** Store as `excalidraw://<drawing_id>` for remote mode or `excalidraw://local/<file_path>` for local mode. Local mode files (.excalidraw) can be committed to the repository directly.
+
+### Figma
+
+**Design creation:** Use the Figma API to create and manage designs. Organize within the configured `project_id` and `team_id`. Leverage Figma's component and auto-layout system for responsive designs.
+
+**Editing:** Edit through the Figma API using the `file_key` to identify the design file. Use Figma's branching feature for non-destructive design iterations. Apply changes through component overrides and variant swapping.
+
+**Token/variable access:** Access Figma Variables API for design tokens — colors, spacing, typography, and component properties. Sync Figma variables with implementation tokens. Use Figma's published styles and local styles for team-wide consistency.
+
+**Export:** Export through the Figma Export API. Supports SVG, PNG, JPG, and PDF. Export at specified scales (1x, 2x, 3x) for responsive assets. Use node IDs to export specific components or frames.
+
+**design_ref storage:** Store as `figma://<file_key>` — the file key from Figma's URL. Reference specific nodes as `figma://<file_key>#node=<node_id>`. For branch-specific references, use `figma://<file_key>?branch=<branch_key>#node=<node_id>`.

package/providers/git.md

@@ -0,0 +1,110 @@
+---
+category: git
+description: Git storage provider — sync H·AI·K·U intent state to remote via intent branches
+---
+
+# Git Provider — Default Instructions
+
+When running in a git repository, the MCP automatically commits and pushes state changes. This behavior is environment-detected, not studio-configured — if git is available, it is used.
+
+## Branch Architecture
+
+H·AI·K·U uses two branch types with fundamentally different lifecycle rules:
+
+### Intent Branch (`haiku/{slug}/main`) — PUSHED
+- **This is where state lives.** Every orchestrator state change commits and pushes here.
+- Kept in sync with the remote at all times.
+- Push failures are non-fatal — commit is preserved locally, pushes on next attempt.
+- PR/MR created from this branch at intent completion (if `auto_pr` is enabled).
+
+### Unit Branches (`haiku/{slug}/{unit}`) — LOCAL ONLY
+- Created as worktrees for parallel unit execution.
+- **Never pushed. Never have PRs opened.**
+- Merged back to the intent branch when the unit completes.
+- Worktree cleaned up after merge.
+
+## Inbound: Provider → H·AI·K·U
+
+On session start, check git state:
+
+- **Branch detection** — verify current branch matches `haiku/{slug}/main`
+- **Remote sync** — check if intent branch is ahead/behind remote; pull if behind
+- **PR/MR status** — if a PR exists for the intent branch, surface its review state
+- **Merge conflicts** — detect conflicts with the default branch; surface before delivery
+
+### Translation (Provider → H·AI·K·U)
+
+| Provider Concept | H·AI·K·U Concept | Translation |
+|---|---|---|
+| Intent branch | Intent | `haiku/{slug}/main` maps to the active intent |
+| Pull Request / Merge Request | Delivery gate / external review signal | PR review decision (APPROVED) or merge state (MERGED) maps to external gate resolution |
+| PR review comments | Review feedback | Surface as context for review agents |
+| Merge conflict | Blocker | Flag intent as needing conflict resolution |
+| Remote ahead/behind | Sync state | Behind = pull needed; ahead = push needed |
+| Default branch (main/master) | Base branch | Target for PR creation |
+
+## Outbound: H·AI·K·U → Provider
+
+### Commit & Push (Intent Branch Only)
+
+Every orchestrator state change triggers:
+1. `git add .haiku/` — stage state changes
+2. `git commit` — atomic state snapshot
+3. `git push` — sync to remote (intent branch only)
+
+State changes that trigger commit + push:
+- Stage start / complete
+- Unit start / complete / reject
+- Hat advance
+- Intent create / complete
+- Go back (stage or phase)
+
+### PR/MR Creation (At Intent Completion)
+
+When `auto_pr` is enabled:
+- **Intent completion** → create PR from `haiku/{slug}/main` to the default branch
+- PR title: intent title from intent.md
+- PR body: summary of stages, units, and review outcomes
+
+### What Does NOT Get Pushed
+
+- Unit worktree branches (`haiku/{slug}/{unit}`) — strictly local
+- Temporary state files — only committed state goes to remote
+- In-progress unit work — only merged results via the intent branch
+
+## External Gate Signal Detection
+
+For stages with `external` review gates, the orchestrator checks approval using two tiers:
+
+### Tier 1: Branch Merge Detection (Primary)
+
+The primary signal is whether the stage branch (`haiku/{slug}/{stage}`) was merged back into the intent main branch (`haiku/{slug}/main`). The orchestrator checks this locally using `git merge-base --is-ancestor` and falls back to checking for merged PRs via `gh`/`glab` (which handles squash merges where the branch commit is not a direct ancestor). This is structural verification — the agent cannot fake a branch merge.
+
+### Tier 2: URL-Based CLI Probing (Fallback)
+
+If a `external_review_url` was recorded in the stage state, the orchestrator also checks PR/MR approval status via CLI tools:
+
+- **GitHub** — `gh pr view <url> --json state,reviewDecision` → advances on `MERGED` or `reviewDecision === "APPROVED"`
+- **GitLab** — `glab mr view <url> --output json` → advances on `merged` state or `approved === true`
+
+This complements Tier 1 by detecting approval before the branch is actually merged. Runs automatically on every `/haiku:pickup`.
+
+## Non-Git Environments
+
+When not running in a git repository, the MCP operates in filesystem mode:
+- State is stored as files on disk in `.haiku/`
+- No commits, no pushes, no branches, no worktrees
+- Units work in-place rather than in worktree isolation
+- All lifecycle operations still function — just without version control
+- **External gates fall back to `ask`** — there is no structural signal (branch merge) to enforce external review, so the framework opens the local review UI for human approval instead of blocking indefinitely
+
+## Provider Config
+
+Configuration lives under `providers.git.config` in `.haiku/settings.yml`.
+Schema: `${CLAUDE_PLUGIN_ROOT}/schemas/providers/github-git.schema.json`
+
+Config fields:
+- `auto_push` → push intent branch after every commit (default: true)
+- `auto_pr` → create PR at intent completion (default: true)
+- `default_branch` → base branch for PRs (default: "main")
+- `remote` → git remote name (default: "origin")

package/providers/knowledge.md

@@ -0,0 +1,98 @@
+---
+category: knowledge
+description: Bidirectional knowledge provider — organizational memory and cross-studio context sharing
+---
+
+# Knowledge Provider — Default Instructions
+
+## Purpose
+
+The knowledge provider manages organizational memory that persists across intents, studios, and projects. While the spec provider handles per-intent documents (PRDs, design docs), the knowledge provider handles **cross-cutting organizational knowledge**: patterns, decisions, learnings, and context that spans multiple intents.
+
+This is the primary mechanism for cross-studio data flow when studios live in different repositories or use different persistence adapters.
+
+## Inbound: Provider → H·AI·K·U
+
+### Context Loading (Session Start)
+- Load organizational patterns and anti-patterns relevant to the current studio
+- Load learnings from previous intents in the same or related studios
+- Load cross-studio context: if this intent depends on work from another studio, pull that studio's outputs from the knowledge provider
+
+### During Elaboration
+- Search for prior art: has similar work been done before?
+- Pull relevant patterns that should inform elaboration
+- Load cross-studio outputs that serve as inputs for this intent
+
+### During Reflection
+- Read existing organizational memory to avoid duplicating learnings
+- Check if patterns discovered in this intent match or contradict existing patterns
+
+### Translation (Provider → H·AI·K·U)
+
+| Provider Concept | H·AI·K·U Concept | Translation |
+|---|---|---|
+| Wiki page / knowledge article | Stage input context | Distill to actionable context for the current stage |
+| Pattern library entry | Elaboration constraint | "Previous work established pattern X — consider it" |
+| Cross-studio output (e.g., sales deal summary) | Intent seed / stage input | Extract the context relevant to this studio's needs |
+| Organizational decision record | Constraint | "Company decided X on {date} — this applies to this work" |
+
+**Key principle:** Organizational knowledge is often scattered across wikis, docs, and conversations. Claude reads what the provider has and distills it into the minimum context needed for the current stage. Not everything in the knowledge base is relevant — Claude filters by intent, studio, and stage context.
+
+## Outbound: H·AI·K·U → Provider
+
+### During Output Persistence
+- Stage outputs scoped as `project` push to the knowledge provider for cross-studio availability
+- Discovery documents, design briefs, behavioral specs → available to other studios via the knowledge provider
+
+### During Reflection (Close Path)
+- Distill learnings into the knowledge provider's format:
+  - Patterns: reusable approaches that worked
+  - Anti-patterns: approaches that failed, with context
+  - Decisions: choices made with rationale
+  - Process insights: improvements that apply broadly
+
+### Translation (H·AI·K·U → Provider)
+
+| H·AI·K·U Concept | Provider Concept | Translation |
+|---|---|---|
+| Stage output (discovery, design brief) | Knowledge article | Format for the provider's audience — not H·AI·K·U frontmatter |
+| Reflection learning | Pattern / anti-pattern entry | Distill to: what, why, when to apply |
+| Settings recommendation | Decision record | Format as: decision, context, consequences |
+| Cross-studio handoff context | Linked article | Write the context the receiving studio needs |
+
+**Key principle:** Don't push raw H·AI·K·U artifacts to the knowledge provider. Translate to the format the organization uses. A reflection.md becomes a retrospective in the team's format. A discovery document becomes a knowledge article. Claude writes for the provider's audience, not for H·AI·K·U's internal consumption.
+
+## Sync: Cross-Studio Data Flow
+
+The knowledge provider enables the critical cross-studio pattern:
+
+```
+Intent A (product-strategy) completes roadmap stage
+  → Pushes roadmap item to knowledge provider
+  → Formats as the organization's standard brief
+
+Intent B (software) starts inception stage
+  → Reads knowledge provider for relevant roadmap items
+  → Distills into inception context and unit criteria
+```
+
+Claude does not need a shared filesystem or same repository. It reads from and writes to the knowledge provider in whatever format that provider uses. The translation happens in Claude's context, not in H·AI·K·U's persistence layer.
+
+### Discovery
+
+When loading cross-studio context, Claude searches the knowledge provider for:
+1. Articles tagged or linked to the triggering intent/studio
+2. Recent articles in relevant categories
+3. Articles matching the current intent's problem space
+
+Claude uses semantic understanding to find relevant knowledge — not just keyword matching.
+
+## Provider Config
+
+Provider-specific configuration lives under `providers.knowledge.config` in `.haiku/settings.yml`.
+Schema: `${CLAUDE_PLUGIN_ROOT}/schemas/providers/{type}.schema.json`
+
+Config fields:
+- `space` / `database` / `folder` — where to read/write in the provider
+- `cross_studio_tag` — tag/label used to mark cross-studio outputs
+- `learnings_location` — where reflections write organizational learnings