H·AI·K·U: review agents, await gate, providers, browse, OAuth

.ai-dlc/haiku-rebrand/discovery.md

@@ -0,0 +1,267 @@
+---
+intent: haiku-rebrand
+created: 2026-04-02T19:46:00Z
+status: active
+---
+
+# Discovery Log: H·AI·K·U Rebrand
+
+Elaboration findings from the April 2, 2026 architecture design session.
+
+## Architecture Decision: Studio/Stage/Persistence Model
+
+The AI-DLC system is being rebranded and rearchitected as H·AI·K·U — a domain-agnostic lifecycle orchestration system. The key insight: all structured work flows through stages of planning, building, and reviewing. Software development is one lifecycle; marketing, hardware, legal are others.
+
+### Core Concepts
+
+- **Studio** — a named lifecycle for a specific domain. Declares stage order and persistence layer.
+- **Stage** — a lifecycle phase. Plans, builds, and reviews its own work. Defines its own hats (roles). One STAGE.md contains everything.
+- **Persistence** — how work is saved. Git for software, Notion for content, filesystem for generic. The studio declares its type.
+- **Outputs** — scope-based persistence. Each stage declares outputs in an `outputs/` directory with frontmatter docs. Scopes: `project` (persists across intents), `intent` (this intent only), `stage` (working context), `repo` (actual source files). Inputs are qualified references in STAGE.md frontmatter, each specifying the producing stage and output name (e.g. `{stage: inception, output: discovery}`).
+
+### Architecture Decision: Unified Stage Loop
+
+The elaborate/execute separation is eliminated. Each stage internally: plan → build → adversarial review → review gate. The user doesn't switch between /elaborate and /execute. A stage just runs.
+
+### Architecture Decision: Hats in Stages
+
+Hats (roles) move from plugin/hats/ directory into each STAGE.md. The hat sequence defined in the stage IS the build workflow. No separate workflows.yml. Security stage is always adversarial because its hats are threat-modeler → red-team → blue-team → reviewer.
+
+### Architecture Decision: Default Ideation Studio
+
+Every project has a studio. The default is "ideation" with universal stages: research → create → review → deliver. Domain-specific studios (software, marketing) specialize this.
+
+### Architecture Decision: Review Gates
+
+Every stage runs automatically. The review gate controls what happens AFTER: auto (advance immediately), ask (pause for user), external (request team review / PR).
+
+### Architecture Decision: Continuous vs Discrete
+
+Not "single-stage vs multi-stage." Both modes run through the same stages. Continuous = autopilot drives transitions, user reviews at gates. Discrete = user explicitly invokes each stage. The choice is per-intent.
+
+### Architecture Decision: Persistence Abstraction
+
+Git is the software studio's persistence adapter, not a system-level assumption. The studio declares `persistence: { type: git, delivery: pull-request }`. Other studios use other adapters.
+
+### Architecture Decision: Product Review is `[external, ask]`
+
+The product stage's review gate is `review: [external, ask]` — the first element (`external`) is the default gate for normal `/haiku:run` runs, serving as the go/no-go decision boundary where the team decides whether to actually build the thing. The `ask` element gives autopilot a valid non-blocking path: `/haiku:autopilot` selects `ask` (the most permissive non-`external` option) and overrides it to `auto`, so autopilot can proceed without a hard external gate while the full external review option remains available for human-driven workflows. The same pattern applies to the security stage.
+
+## Codebase Context
+
+**Stack:** TypeScript, Bash (shell scripts), Next.js 15 (website), Markdown (specs/docs)
+**Architecture:** Claude Code plugin (plugin/), static website (website/), methodology paper
+**Conventions:** YAML frontmatter in markdown, SKILL.md for skill definitions, shell libraries in plugin/lib/
+
+## What Dissolves
+
+- `plugin/hats/` directory — hats move into STAGE.md files
+- `plugin/workflows.yml` — stages define their own hat sequences
+- Workflow selection sub-skill — not needed
+- `phases/ELABORATION.md` and `phases/EXECUTION.md` — stage body is context for everything
+- The elaborate/execute command split — replaced by unified stage loop
+- Software-only assumption — persistence adapters make it domain-agnostic
+
+## What Already Changed (This Session)
+
+- `pass` renamed to `stage` across all plugin files, hooks, schemas, types
+- `plugin/passes/` → `plugin/stages/` (then further into studios)
+- Stage definitions created with input/output model (inputs in frontmatter, outputs/ directory)
+- Studio infrastructure: studio.sh, stage.sh, STUDIO.md
+- Built-in software studio with design/product/dev stages
+- STUDIO-SPEC.md written
+- HTML architecture visualization (3 versions in Downloads)
+
+## Design Artifacts
+
+These artifacts capture the full architecture design and are included in this intent for historical reference:
+
+- **`architecture-spec.md`** — Full technical specification: file structure, STAGE.md schema, FSM model, execution model, settings, resolution logic, custom stage/studio examples, migration path, backwards compatibility guarantees.
+- **`architecture-viz.html`** — Interactive HTML visualization: core lifecycle loop, stage anatomy, software studio pipeline with hats/review/outputs grid, ideation studio (default), marketing studio example, persistence layer comparison, continuous vs discrete modes, knowledge pools, full hierarchy diagram.
+
+## Architecture Decision: Input/Output Architecture
+
+Stages declare their data flow through two mechanisms: **inputs** (qualified references in STAGE.md frontmatter) and **outputs** (self-describing frontmatter docs in an `outputs/` directory within the stage).
+
+### Inputs
+
+Qualified references in STAGE.md frontmatter. Each entry specifies the producing stage and the output name within that stage. A bare slug is ambiguous -- two stages could have outputs with the same name. The `stage` + `output` pair together resolve to the exact persisted location.
+
+```yaml
+---
+name: security
+description: Threat modeling and penetration testing
+hats: [threat-modeler, red-team, blue-team, reviewer]
+review: external
+unit_types: [security, backend]
+inputs:
+  - stage: product
+    output: behavioral-spec
+  - stage: development
+    output: code
+---
+```
+
+The orchestrator resolves each qualified input to the producing stage's output definition, then reads from its persisted location.
+
+### Input Loading: Plan Phase Only
+
+Inputs are loaded during the **plan phase** of a stage, not the build phase. During planning, the orchestrator loads all stage inputs as context for decomposing work into units and defining criteria. During the build phase, individual units declare their own `## References` section listing the specific artifacts the builder needs -- the full input set is NOT loaded into each builder agent.
+
+This prevents context bloat: a stage might declare 5 inputs, but a given unit only needs 2 of them. The plan phase uses the full picture; the build phase uses only what each unit requires.
+
+### Unit References
+
+Unit specs get a `## References` section populated during the plan phase:
+
+```markdown
+## References
+- .haiku/intents/{intent-slug}/knowledge/DISCOVERY.md
+- .haiku/intents/{intent-slug}/knowledge/BEHAVIORAL-SPEC.md
+```
+
+The builder agent reads ONLY these files, not the entire knowledge pool. This section is populated based on what the unit actually needs, derived from the stage inputs and the unit's specific scope of work.
+
+### Outputs
+
+Each stage has an `outputs/` directory containing self-describing frontmatter docs. Each output file declares its name, persistence scope, format, and whether it's required. The body provides guidance for what to produce.
+
+```
+plugin/studios/software/stages/inception/
+├── STAGE.md
+└── outputs/
+    └── DISCOVERY.md         # scope: intent, format: text
+```
+
+### Output Doc Schema
+
+```yaml
+---
+name: discovery
+location: .haiku/intents/{intent-slug}/knowledge/DISCOVERY.md
+scope: intent
+format: text
+required: true
+---
+
+# Discovery Output Guide
+
+When exploring the domain, document:
+- Every entity and its fields
+- Every API endpoint and its behavior
+- Architecture patterns and constraints
+- Quality gate candidates
+```
+
+### Output Scopes
+
+| Scope | Persisted To | Lifespan |
+|-------|-------------|----------|
+| `project` | `.haiku/knowledge/{name}.md` | Persists across intents |
+| `intent` | `.haiku/intents/{intent-slug}/knowledge/{name}.md` | This intent only |
+| `stage` | `.haiku/intents/{intent-slug}/stages/{stage}/{name}` | Working context for this stage's units only |
+| `repo` | Project source tree | Actual code, configs — permanent |
+
+### Example Output Types
+
+- `ARCHITECTURE.md` — scope: project, format: text (persists to `.haiku/knowledge/`)
+- `DISCOVERY.md` — scope: intent, format: text
+- `DESIGN-BRIEF.md` — scope: stage, format: text (only for this stage's units)
+- `CODE.md` — scope: repo, format: code (actual source files)
+- `WIREFRAMES.md` — scope: stage, format: design
+
+### What This Replaces
+
+- No `knowledge/` directory inside stages — replaced by `outputs/`
+- No `requires:` or `produces:` fields in STAGE.md frontmatter — replaced by `inputs:` (frontmatter list) and `outputs/` (directory of docs)
+- No `output_path:` in knowledge templates — replaced by `location:` with scope-based paths
+
+### Directory Structure
+
+```
+.haiku/
+├── settings.yml
+├── knowledge/                          # Project-scoped outputs land here
+│   ├── ARCHITECTURE.md
+│   └── CONVENTIONS.md
+├── studios/                            # Custom/override studios
+└── intents/
+    └── {name}/
+        ├── intent.md
+        ├── knowledge/                  # Intent-scoped outputs land here
+        │   ├── DISCOVERY.md            ← inception wrote this
+        │   ├── DESIGN-BRIEF.md         ← design stage wrote this
+        │   └── THREAT-MODEL.md         ← security stage wrote this
+        ├── stages/
+        │   ├── inception/
+        │   │   ├── state.json
+        │   │   ├── WORKING-NOTES.md    ← stage-scoped output (lives here)
+        │   │   └── units/
+        │   ├── design/
+        │   │   ├── state.json
+        │   │   └── units/
+        │   │       ├── unit-01-wireframes.md
+        │   │       └── unit-02-tokens.md
+        │   └── development/
+        │       ├── state.json
+        │       └── units/
+        │           ├── unit-01-auth-api.md
+        │           └── unit-02-frontend.md
+        └── state.json                  # { active_stage, mode, studio }
+```
+
+## Rename Map (from exploration agent)
+
+### Directories and files to rename
+| From | To |
+|------|-----|
+| `.ai-dlc/` | `.haiku/` |
+| `plugin/hats/` | (removed — hats move into STAGE.md) |
+| `plugin/workflows.yml` | (removed — stages define hat sequences) |
+| `plugin/stages/` | `plugin/studios/{name}/stages/{stage}/STAGE.md` |
+| `plugin/passes/` | (already renamed to stages, then into studios) |
+
+### Code identifier renames
+| From | To |
+|------|-----|
+| `dlc_*` functions | `hku_*` functions |
+| `aidlc_*` telemetry | `haiku_*` telemetry |
+| `_DLC_*` guard vars | `_HKU_*` guard vars |
+| `DLC_*` constants | `HKU_*` constants |
+| `CLAUDE_PLUGIN_ROOT` | (unchanged — this is a Claude Code convention) |
+
+### Frontmatter field renames
+| From | To |
+|------|-----|
+| `passes:` | `stages:` (already done) |
+| `active_pass:` | `active_stage:` (already done) |
+| `pass:` | `stage:` (already done) |
+
+### Command renames
+| From | To |
+|------|-----|
+| `/ai-dlc:elaborate` | `/haiku:stage` (or `/haiku:run` for continuous) |
+| `/ai-dlc:execute` | (dissolved into stage loop) |
+| `/ai-dlc:setup` | `/haiku:setup` |
+| `/ai-dlc:autopilot` | `/haiku:run` (continuous mode) |
+| `/ai-dlc:review` | `/haiku:review` |
+| `/ai-dlc:followup` | `/haiku:followup` |
+| `/ai-dlc:quick` | `/haiku:quick` |
+| `/ai-dlc:adopt` | `/haiku:adopt` |
+| `/ai-dlc:refine` | `/haiku:refine` |
+| `/ai-dlc:release-notes` | `/haiku:release-notes` |
+| `/ai-dlc:compound` | `/haiku:compound` |
+| `/ai-dlc:blockers` | `/haiku:blockers` |
+| `/ai-dlc:backpressure` | `/haiku:backpressure` |
+| `/ai-dlc:fundamentals` | `/haiku:fundamentals` |
+| `/ai-dlc:completion-criteria` | `/haiku:completion-criteria` |
+
+### Files that reference ai-dlc (from exploration)
+- **Libraries (plugin/lib/):** config.sh, dag.sh, stage.sh, studio.sh, knowledge.sh, state.sh, deps.sh, parse.sh, design-blueprint.sh, telemetry.sh
+- **Hooks (plugin/hooks/):** inject-context.sh, subagent-context.sh, quality-gate.sh, redirect-plan-mode.sh, session-start.sh, stop-hook.sh
+- **Skills:** All 20+ SKILL.md files across elaborate, execute, setup, review, etc.
+- **Schemas:** settings.schema.json, all provider schemas
+- **Types:** shared/src/types.ts
+- **Plugin metadata:** .claude-plugin/plugin.json, .claude-plugin/hooks.json
+- **Website:** All content in website/content/docs/, website/content/papers/, website/content/blog/
+- **Root:** CLAUDE.md, CHANGELOG.md, README.md

.ai-dlc/haiku-rebrand/intent.md

@@ -0,0 +1,97 @@
+---
+workflow: default
+git:
+  change_strategy: intent
+  auto_merge: true
+  auto_squash: false
+announcements: [changelog, release-notes]
+stages: []
+active_stage: ""
+iterates_on: ""
+created: 2026-04-02
+status: completed
+epic: ""
+quality_gates: [{name: tests, command: "bun test"}, {name: lint, command: "bun run lint"}, {name: typecheck, command: "bun run typecheck"}]
+---
+
+# H·AI·K·U Rebrand — From AI-DLC to Domain-Agnostic Lifecycle Orchestrator
+
+## Problem
+
+AI-DLC is a software development lifecycle tool hardcoded to three disciplines (design, product, dev) with a monolithic 2,400-line elaboration skill. It separates "elaboration" (spec) and "execution" (build) as distinct commands. It can't support custom lifecycles — a security team, hardware team, or marketing team has no way to define their own workflow. The system assumes git as the only persistence mechanism.
+
+## Solution
+
+Rebrand AI-DLC to H·AI·K·U and implement a studio/stage/persistence architecture:
+
+1. **Studios** define named lifecycles for any domain. The default "ideation" studio works for every discipline. The "software" studio specializes for software development with stages: inception → design → product → development → operations → security.
+
+2. **Stages** replace the elaborate/execute split. Each stage plans, builds, and reviews its own work internally. Stages define their own hats (roles) — no separate hats directory or workflows file. One STAGE.md per stage contains everything.
+
+3. **Persistence** is abstracted behind the studio. Git (branches, commits, PRs) is the software adapter. Other studios use other adapters (Notion, filesystem, CAD systems).
+
+4. **Continuous vs Discrete** modes let the user choose per-intent: autopilot drives stage transitions (continuous) or user invokes each stage (discrete). Both follow the same pipeline.
+
+5. The mechanical rebrand: `.ai-dlc/` → `.haiku/`, `/ai-dlc:*` → `/haiku:*`, all references across plugin, paper, website, and docs.
+
+## Domain Model
+
+### Entities
+- **Studio** — named lifecycle template. Declares stage order and persistence type. Lives in `plugin/studios/{name}/STUDIO.md` or `.haiku/studios/{name}/STUDIO.md`.
+- **Stage** — lifecycle phase with hats, review mode, inputs (frontmatter list), and outputs (`outputs/` directory of self-describing docs). Lives in `studios/{name}/stages/{stage}/STAGE.md`.
+- **Persistence Adapter** — how work is saved/versioned/delivered. Git adapter is the default for software.
+- **Intent** — what's being built. Lives in `.haiku/intents/{name}/intent.md`.
+- **Unit** — discrete piece of work within a stage. Lives in `.haiku/intents/{name}/stages/{stage}/units/`.
+- **Bolt** — one cycle through a stage's hat sequence.
+- **Output** — a self-describing frontmatter doc in a stage's `outputs/` directory. Declares name, location, scope, format, and whether required. Scopes: `project` (`.haiku/knowledge/`), `intent` (`.haiku/intents/{name}/knowledge/`), `stage` (`.haiku/intents/{name}/stages/{stage}/`), `repo` (project source tree).
+- **Review Gate** — auto | ask | external. Controls what happens after a stage completes.
+
+### Relationships
+- Studio has many Stages (ordered)
+- Studio has one Persistence Adapter
+- Stage has many Units
+- Stage has many Hats (ordered — the hat sequence IS the build workflow)
+- Stage has one Review Gate
+- Unit has many Bolts
+- Intent references one Studio
+- Intent has many Stages (from its studio)
+- Stage has many Outputs (declared in `outputs/` directory, persisted by scope)
+- Stage has many Inputs (list in frontmatter, resolved from prior stage outputs)
+
+### Data Sources
+- Plugin source: `plugin/` directory (skills, hooks, lib, schemas)
+- Website: `website/` (Next.js 15 static site)
+- Paper: `website/content/papers/ai-dlc-2026.md`
+- Settings: `.ai-dlc/settings.yml` (→ `.haiku/settings.yml`)
+- Project-scoped outputs: `.haiku/knowledge/` (persist across intents)
+- Intent-scoped outputs: `.haiku/intents/{name}/knowledge/` (per-intent)
+- Stage-scoped outputs: `.haiku/intents/{name}/stages/{stage}/` (working context)
+- Architecture spec: `plugin/skills/elaborate/STUDIO-SPEC.md`
+- Architecture viz: `~/Downloads/haiku-architecture-v1.html`
+
+## Success Criteria
+- [ ] All `.ai-dlc/` references → `.haiku/` across the entire codebase
+- [ ] All `/ai-dlc:*` commands → `/haiku:*`
+- [ ] All "AI-DLC" branding → "H·AI·K·U" in user-facing content
+- [ ] Default ideation studio created (`plugin/studios/ideation/`)
+- [ ] Software studio created (`plugin/studios/software/`) with 6 stages
+- [ ] Each stage has STAGE.md with hats, review mode, guidance, inputs list, and outputs/ directory
+- [ ] plugin/hats/ directory removed — hats live in STAGE.md
+- [ ] plugin/workflows.yml removed — stages define their own hat sequences
+- [ ] Unified stage orchestrator skill replaces separate elaborate/execute skills
+- [ ] Persistence abstraction with git adapter as default
+- [ ] Settings schema updated (studio: field, persistence config)
+- [ ] Paper terminology updated (pass → stage, new hierarchy documented)
+- [ ] Website docs updated for H·AI·K·U terminology
+- [ ] CLAUDE.md terminology table updated
+- [ ] All existing tests pass after rebrand
+- [ ] Continuous mode (default) works identically to current single-stage behavior
+
+## Context
+
+This intent captures the architecture design session from April 2, 2026. The conversation evolved from a simple elaborate skill refactor into a complete rethinking of the system's domain model — discovering that the studio/stage pattern is domain-agnostic and that the elaborate/execute separation was an artifact of software-centric thinking. The "pass" concept was renamed to "stage," hats were dissolved into stages, workflows were dissolved into studios, and persistence was abstracted to support non-software domains.
+
+Key artifacts from the session:
+- `plugin/skills/elaborate/STUDIO-SPEC.md` — technical specification
+- `~/Downloads/haiku-architecture-v1.html` — interactive visualization
+- `~/Downloads/ai-dlc-architecture-v2.html` / `v3.html` — earlier iterations