@jaybeeuu/agent-cortex 1.20.0

package/docs/ideas/auto-model-selection.md

@@ -0,0 +1,75 @@
+# Idea: Auto-Model Selection Plugin
+
+## Status
+Backlog idea (not implementation-ready) — **direction: evaluate and adopt existing package**
+
+## Why it might be useful
+PI has no intelligent model selection. Users must manually choose models, which means they either over-provision (expensive models for simple tasks) or under-provision (weak models for complex work). Rate limits hit without warning, forcing manual model switching mid-session. An auto-selection plugin would optimize cost/performance by matching model capability to task complexity, and provide seamless fallbacks when rate limits are hit.
+
+## How we might do it
+**Evaluate and adopt an existing PI extension** rather than building from scratch. The ecosystem already has well-maintained packages that cover task-based routing and rate-limit fallbacks. The goal is to:
+
+1. **Evaluate the top candidates** (see "Packages to evaluate" below)
+2. **Pick the best fit** for agent-cortex's workflow (beads, pipeline stages, HITL/AFK classification)
+3. **Install and configure** it, possibly with light customisation if needed
+4. **Document** the chosen package and configuration in agent-cortex docs
+
+## Packages to evaluate (in priority order)
+**Top candidates — cover both task-based routing AND fallbacks:**
+1. **`@kylebrodeur/pi-model-router`** — per-turn routing to high/medium/low tiers based on task intent, context size, budget, with automatic fallback chains and rate-limit recovery. Well-documented fork of yeliu84's original.
+2. **`pi-auto-router`** — multi-provider routing with same-request failover, budget-aware policies, and quota-aware fallback.
+3. **`pi-tiered-router`** — routes different *phases* (planner/validator/executor/tool-parser) to different models. Quality-first, not cost-saving.
+
+**Fallback-only (simpler, if routing is overkill):**
+- **`pi-auto-models`** — Claude→Codex quota switching with 429/529 recovery
+- **`pi-provider-fallback`** — cross-provider fallback chain with TUI config
+
+**Evaluation criteria:**
+- Does it integrate cleanly with PI's existing provider/model system?
+- Does it respect user's explicit model choice, or override it?
+- How does it handle context window mismatches on fallback?
+- Is it configurable per-project?
+- Does it have fallback chains or just single fallback?
+- Rate-limit detection and retry logic
+- Documentation quality and maintenance status
+
+## When to think about it
+- After current feature stabilisation (refactor-to-template epic, npm publishing, system prompt improvements)
+- Not blocked, but benefits from stable extension infrastructure
+
+## Priority
+Medium / backlog — valuable for cost optimisation and reliability, but not urgent. Current manual model selection works, just isn't optimal.
+
+## Open questions
+- How to classify task complexity? Heuristics (file count, prompt length, keywords)? Or let user tag tasks?
+- What defines a "model class"? Cost tier, context window size, reasoning capability, speed?
+- Should the plugin override the user's explicit model choice, or only activate when no model is selected?
+- How to handle context window mismatches when falling back (e.g., 200k → 128k)?
+- Should this be configurable per-project (different policies for different repos)?
+
+## Existing packages in the ecosystem
+Several published packages already address parts of this problem:
+
+### Fallback / rate-limit recovery
+- **`pi-provider-fallback`** — cross-provider fallback with interactive TUI config
+- **`pi-auto-models`** — primary/fallback switching on quota (Claude→Codex default), 429/529 recovery
+
+### Task-based / tier routing
+- **`pi-model-router`** (yeliu84, forked by @kdejaeger and @kylebrodeur) — per-turn routing to high/medium/low tiers based on task intent, context size, budget, with automatic fallbacks
+- **`pi-model-auto`** — routes by Low/Medium/High/Ultra capability modes per turn
+- **`pi-tiered-router`** — routes different phases (planner/validator/executor/tool-parser) to different models
+
+### Full auto-router with failover
+- **`pi-auto-router`** — multi-provider routing with same-request failover, budget-aware policies
+- **`@ifi/pi-extension-adaptive-routing`** — adaptive routing with local telemetry persistence
+
+### Model selection (manual)
+- **`pi-model-switch`** — direct model switching tool
+- **`pi-model-select`** — `/select-model` with favourites and fuzzy search
+
+## Notes
+- **The ecosystem is active** — this space is already well-served. Before building, evaluate whether an existing package (especially `pi-model-router` or `pi-auto-router`) already meets the need.
+- **Gap analysis needed**: compare existing packages against the original requirements (task-based class selection + rate-limit fallbacks) to see if anything is genuinely missing.
+- **Partial solutions exist in PI core**: OpenRouter's routing config supports fallbacks and provider ordering, but only within OpenRouter. Cross-provider fallback requires an extension.
+- **Implementation approach** (if building): likely a PI extension that registers a "smart-router" provider, which internally delegates to real providers based on task classification and availability.
+- **Research done**: reviewed PI docs on providers, models, and extensions. Searched npm and pi.dev for existing packages.

package/docs/ideas/improve-pi-system-prompt.md

@@ -0,0 +1,34 @@
+# Idea: Improve PI System Prompt
+
+## Status
+Backlog idea (not implementation-ready)
+
+## Why it might be useful
+PI's current system prompt is weak. Agents consistently get off track, spend excessive tokens spinning their wheels or going off on tangents, fail to check in when problems are hit, and generally behave like inexperienced code goblins. This wastes tokens, slows down task completion, and forces the user to constantly redirect the agent. A stronger system prompt would produce more focused, disciplined agents that know when to stop and ask.
+
+## How we might do it
+Build improved behavioural instructions into agent-cortex — layered on top of or replacing PI's default system prompt. Key improvements:
+
+1. **Loop prevention / circuit-breakers** — hard limits on retry attempts (e.g. 2-attempt limit before stopping and asking), no repeated tool execution without rationale
+2. **Task-focus discipline** — stronger scoping instructions, no tangential refactoring, atomic changes
+3. **Check-in triggers** — explicit rules for when the agent must stop and present options to the user
+
+A Gemini-generated execution protocol prompt exists as a possible starting point (see Notes), but will need significant customisation for agent-cortex.
+
+## When to think about it
+- Land the current work first (refactor-to-template epic, bead workflow polish, CI/CD pipeline)
+- **Next priority after current work** — this is urgent-ish
+
+## Priority
+High — after current work lands. Directly impacts daily productivity and token efficiency.
+
+## Open questions
+- Layer on top of PI's default prompt, or replace it entirely?
+- Should PI's current system prompt be reviewed for nonsense that can be chopped out?
+- Which guardrails from the Gemini starter are genuinely useful vs redundant with existing skills (e.g. `git-workflow` already covers destructive commands, `style-code` covers scope discipline)?
+- How should circuit-breakers interact with skills like `run-pipeline-stage` that already have structured workflows?
+
+## Notes
+- **Gemini starter prompt** exists (see conversation from 2026-08-05) covering loop prevention, action scope, context management, execution workflow order, and working state maintenance. Useful starting material but needs heavy customisation.
+- **Incompatibility to fix**: the starter's "Working State Maintenance" section proposes `.pi/PLAN.md` files for complex tasks. This is incompatible with agent-cortex — we use **beads (bd)** for task tracking and pipeline stages, not flat markdown plan files. This section needs to be replaced with bead-aware equivalents (e.g. updating bead notes, using pipeline stage state).
+- **Overlap with existing skills**: several guardrails already exist in agent-cortex skills (`git-workflow`, `style-code`, `run-pipeline-stage`). The biggest gaps are **loop prevention / circuit-breakers** and **check-in discipline** — these aren't enforced anywhere today.

package/docs/ideas/model-selector.md

@@ -0,0 +1,40 @@
+# Idea: model-selector
+
+## Status
+Backlog idea (not implementation-ready)
+
+## Created
+2026-07-12
+
+## Problem
+Selecting the right model for a task is manual and brittle. When a model is unavailable (rate-limited, down, or lacking capability), there's no automatic fallback. You have to know which model IDs to type into `/model` and remember which providers offer which capabilities.
+
+## Who benefits
+Anyone using PI who runs multiple models/providers. The extension makes model selection declarative: "I want to write code" → extension picks the best available model (and falls back if limits are hit).
+
+## Proposed outcome
+A PI extension that defines an abstraction for selecting models based on task/use case. Users declare "use case → model(s) with fallbacks" in config, and the extension handles selection and failover automatically.
+
+Key capabilities:
+- **Use-case profiles**: e.g. `code`, `chat`, `review`, `architect` — each maps to a primary model + ordered fallbacks
+- **Automatic fallback**: if the primary model returns a 429 or error, drop to the next in the chain
+- **Task-based selection**: think "I want this model to write code" instead of choosing a specific model ID
+- **Configurable**: profiles defined in settings.json or a dedicated config file
+
+## Validity check
+- Evidence we already have: The existing `tiny-model.ts` lib in this repo already shows the pattern of configuring a model by provider/id string and looking it up via `modelRegistry.find()`. The PI extension API supports `before_provider_response` (for catching 429s) and `model_select` events.
+- Riskiest assumption: That use-case profiles are a useful abstraction — users may prefer to just name a model family and let fallback be implicit.
+- What would invalidate this idea: If PI adds built-in model routing/fallback, or if users find the abstraction adds confusion rather than removing it.
+
+## Constraints
+- Must not add LLM calls internally (per extension conventions in AGENTS.md)
+- Must work with the existing `modelRegistry` API — no monkey-patching
+- Storage/config should go in settings.json or `~/.pi/agent-cortex/` (global, cross-project)
+
+## Next validation step
+Sketch the config schema and test it against real usage patterns. Does the profile abstraction hold up for the models/providers you actually use?
+
+## Notes
+- Initial conversation during planning session 2026-07-12. Idea recorded as backlog, to be fleshed out when time permits.
+- Could draw on patterns from OpenRouter's routing and the existing `modelOverrides` in models.json.
+- The `notify` extension already intercepts provider responses — similar pattern for catching rate limits.

package/docs/ideas/pi-task-memory.md

@@ -0,0 +1,34 @@
+# Idea: PI Task Memory Skill
+
+## Status
+Backlog idea (not implementation-ready)
+
+## Why it might be useful
+PI has no built-in task memory. Agents lose context between sessions — they can't track what a task has done, what decisions were made, or where they left off. A skill that persists task-scoped knowledge in structured markdown would let agents pick up work without re-discovering context from scratch, and give humans a readable audit trail they can review or promote into real documentation.
+
+## How we might do it
+**Possibly build on top of `bd remember`** rather than creating a separate storage system. Worth exploring whether `bd remember`'s existing infrastructure (persistence, cross-session survival, auto-injection) could be extended with task-scoping and structure, vs building something standalone.
+- **Task-linked** — memories keyed to specific bead/task IDs so they can be retrieved in context
+- **Progressively discoverable** — the agent recalls relevant memories as it picks up work, not all at once
+- **Structured** — consistent format that's easy to scan, edit, or promote
+- **Promotable** — easy to elevate a memory into real repo documentation (e.g. `docs/`, `AGENTS.md`) once it's proven stable
+
+If `bd remember` turns out to be the right foundation, the skill would add **task-scoping discipline, structure, and a promotion workflow** on top. But that's to be determined.
+
+## When to think about it
+- After the current skill set stabilises (refactor-to-template work, bead workflow, CI/CD pipeline)
+- Not blocked by anything, but benefits from a stable foundation
+
+## Priority
+Low / backlog — useful but not urgent. Current memory surfaces (bd remember, context-mode) cover some of the gap already.
+
+## Open questions
+- What triggers writing a memory? (Agent decides? Skill hook on task close? Specific prompts?)
+- What does "progressively discoverable" mean in practice — agent reads task memories at session start, or on-demand when picking up a task?
+- What does "elevate into docs" look like — export memory to markdown file, or just reference the memory in docs?
+- How to structure memory keys for task-scoping? (e.g. `task-<bead-id>-<topic>`, or a naming convention?)
+
+## Notes
+- **What bd remember already provides**: persistent cross-session memories, auto-injection at `bd prime`, searchable via `bd memories <keyword>`, stored in Dolt database.
+- **Worth exploring**: could this skill layer task-scoping discipline (memories keyed to bead IDs), structured format, progressive discovery (not all memories at once), and a promotion workflow on top of `bd remember`? Or does it need its own system?
+- Could be a **PI extension** (event hooks) rather than a skill (invoked on-demand) if memories should be written automatically during task work.

package/docs/ideas/qa-extension.md

@@ -0,0 +1,43 @@
+# Idea: qa-extension
+
+## Status
+Backlog idea (not implementation-ready)
+
+## Created
+2026-07-12
+
+## Problem
+When an agent needs clarification during a task (e.g. during a grilling session, resolving ambiguity, or making a recommendation), it has no structured way to ask the user a question and wait for an answer. The current workaround is unstructured prompting — the agent guesses, rambles, or proceeds with incomplete information. This makes grilling sessions less productive and wastes turns.
+
+## Who benefits
+Anyone using PI agents for interactive work — especially during planning, grilling, and design sessions where the model needs to ask a series of questions one at a time and get focused answers.
+
+## Proposed outcome
+A PI extension that registers a `qa` or `ask` tool that the LLM can call to ask the user a question. The tool:
+- Presents the question (and optionally multiple-choice options or a recommendation)
+- Pauses the agent and waits for the user's response
+- Returns the user's answer to the model so it can continue
+- Supports multi-turn Q&A sessions (series of questions)
+
+This mirrors the built-in `ask_clarification` / `question` tools in Claude Code, GitHub Copilot Chat, and similar coding agents.
+
+## Validity check
+- Evidence we already have: The PI extension API supports custom tools with user interaction via `ctx.ui` (input, confirm, select). The `subagent` extension already demonstrates complex async tool patterns. Claude Code and Copilot both ship this — it's a proven pattern.
+- Riskiest assumption: That the tool execution model in PI can support a "pause and wait for user input" flow without blocking the agent loop awkwardly.
+- What would invalidate this idea: If PI adds a built-in `ask_user` tool, or if the UX of blocking the agent loop for input feels worse than the current unstructured approach.
+
+## Constraints
+- Must work in both TUI and RPC modes (graceful fallback in non-interactive modes)
+- Should support at minimum: free-text input, confirm/deny, and multiple-choice selection
+- Questions and answers should be visible in the session history so they survive compaction
+- Must handle abort (Ctrl+C mid-question) gracefully
+
+## Next validation step
+1. **Investigate existing extensions first** — search PI's built-in tools, extension registry, and community repos for an existing `ask`/`qa`/`question` tool before building. May already be available.
+2. If no existing extension: check the PI tool execution model to see if a custom tool can return a partial result and then receive follow-up input from the user. Look at how `ctx.ui.input()` and `ctx.ui.confirm()` behave inside tool execution — can they block and return, or do they need a different pattern?
+
+## Notes
+- **Needs investigation** — check for existing PI extensions/tools before building.
+- Initial conversation 2026-07-12. Motivated by making grilling sessions more efficient — the grill-me skill asks one question at a time, and a structured Q&A tool would make that flow tighter.
+- Related to `grill-me` skill (`skills/productivity/grill-me/SKILL.md`) — this extension could become the runtime that grill-me delegates its questioning to.
+- Possible names: `/ask`, `qa`, `question` tool.

package/docs/inspirations.md

@@ -0,0 +1,33 @@
+# Inspirations
+
+A living record of external repos and promoted internal research that inform agent-cortex skill and agent design.
+
+## Internal research docs
+
+- [Gas City research](research/gas-city-research.md)
+- [Skill pattern research notes](research/skill-patterns-research.md)
+- [Skill design research](research/skill-design-research.md)
+- [Skill improvements analysis](research/skill-improvements-analysis.md)
+
+## addyosmani/agent-skills
+
+**URL**: https://github.com/addyosmani/agent-skills  
+**Last reviewed**: 2026-05-26  
+**Type**: Public skill collection (Claude Code / OpenCode)
+
+### Structure patterns worth noting
+
+| Pattern | Description | Adopted? |
+|---|---|---|
+| Consistent skeleton | Every skill follows a shared, predictable section model | Partially |
+| "When NOT to use" | Explicit out-of-scope conditions in every skill | Planned |
+| "Common Rationalizations" | Debunks excuses for skipping process steps | Planned |
+| "Red Flags" | Concrete anti-patterns to detect during execution | Planned |
+| Verification checklist | Completion gate in each skill | Planned |
+| Cross-references | `See Also` links to related skills | Planned |
+
+## Matt Pocock — skills repo
+
+**URL**: https://github.com/mattpocock/skills  
+**Last reviewed**: 2026-05-26  
+**Type**: Public skill collection

package/docs/research/gas-city-research.md

@@ -0,0 +1,256 @@
+# Gas City Research Notes
+
+This is a promoted research note.
+
+
+Research conducted 2026-05-03/04. Source: `gastownhall/gascity` and related `gastownhall/*` repos.
+
+---
+
+## What is Gas City?
+
+Gas City is a Go-based multi-agent orchestration SDK (`gc` CLI, v1.0.0, released 2026-04-21, MIT licence).
+It manages **live interactive agent sessions** (Claude Code, Codex CLI, etc. running in tmux) rather than
+making raw LLM API calls. It is not a replacement for LLM API access — it is a rack manager for persistent
+agent processes.
+
+Gas City is built on the **MEOW stack** (Molecular Expression of Work) — the same `bd` (beads) tooling
+already in use in this repo.
+
+---
+
+## The MEOW Stack
+
+MEOW = **Molecular Expression of Work**. A layered work-decomposition and tracking infrastructure:
+
+```
+Formulas / Orders    ← TOML templates defining workflow shape + when it fires
+       ↑
+Molecules / Wisps    ← durable chained bead workflows; instances of formulas
+       ↑
+Epics                ← hierarchical bead grouping (parent/child beads)
+       ↑
+Beads                ← atomic git-backed work units (the bd CLI)
+```
+
+**Core insight:** work is the primitive, not orchestration. The controller is a thin layer on top of the
+MEOW stack. Work definition and tracking is what matters; orchestration shape is configurable on top.
+
+**GUPP (Gas Town Universal Propulsion Principle):** *"If you find something on your hook, you run it."*
+Agents are stateless pistons; the bead store is the engine.
+
+---
+
+## Key Concepts
+
+### Rigs
+A **rig** is an external project directory (git repo) registered with a city. Each rig gets its own beads
+database, agent hooks, and pack expansion. One city can manage multiple rigs (multiple repos) — this is
+the primary multi-repo use case.
+
+```toml
+# city.toml
+[[rigs]]
+name = "my-api"
+
+[[rigs]]
+name = "my-frontend"
+```
+
+### City
+A deployment of packs + rigs under one controller. The controller runs as a persistent Go process managing
+all sessions in all rigs.
+
+### Packs / Formulas
+Reusable TOML configuration bundles. A **formula** is a TOML workflow template defining steps and
+dependencies. A **molecule** is an instance of a formula — materialised as beads in the store.
+
+### Convergence
+The outer retry loop. When a wisp closes, the controller's `HandleWispClosed()` (a 9-step deterministic
+Go algorithm) evaluates a gate and decides: `iterate` (new wisp), `approved` (done), `no_convergence`
+(blocked), or `waiting_manual` (human required).
+
+### Orders
+Scheduled formula dispatch. Five trigger types: `cooldown`, `cron`, `condition` (shell exit 0), `event`
+(bead.closed on city bus), `manual`. Can dispatch a formula to an agent pool, or run a shell script
+directly (`exec` orders — no LLM involved).
+
+---
+
+## What Gas City Gives Us
+
+| Capability | Status |
+|---|---|
+| Multi-repo orchestration (rigs) | ✅ Native — primary use case |
+| Rack / dashboard (`gc status`, SPA) | ✅ Built-in |
+| Agent lifecycle (crash recovery, idle-kill, restart) | ✅ Built-in |
+| Worktree isolation (per-agent git branch) | ✅ `isolation = "worktree"` in agent config |
+| Concurrent feature work (multiple agents, multiple branches) | ✅ Via pool + worktree isolation |
+| Scheduling / reactive triggers (Orders) | ✅ 5 trigger types |
+| Deterministic workflow routing | ✅ Controller is Go state machine (no LLM in routing path) |
+| Formula-based step sequencing | ✅ TOML DAG, `needs` dependencies, executed by `bd` |
+| Feature backlog isolation (separate bead stores) | ⚠️ Requires separate rigs; not automatic |
+| Cross-repo bead dependencies | ❌ Not supported — issue #587, milestone `1.0+`, no timeline |
+| Native loops in formulas | ❌ Formulas are DAGs; loops require the convergence engine |
+
+---
+
+## Architecture: Determinism vs. Agents
+
+Gas City has a sharp boundary. The Go controller owns all routing; LLMs only do work and emit a verdict.
+
+```
+Agent works through formula steps
+    → writes convergence.agent_verdict = "approve" | "block"
+    → closes wisp
+
+Controller HandleWispClosed() [pure Go, 9-step algorithm]
+    → reads verdict (scoped to this wisp by agent_verdict_wisp)
+    → runs gate shell script (exit 0 = pass, exit 1 = fail)
+    → ActionApproved  → state=terminated, done
+    → ActionIterate   → pour new wisp, re-dispatch to agent
+    → ActionNoConvergence → state=terminated, blocked
+    → ActionWaitingManual → human must gc conv approve
+```
+
+**ACL enforcement:** agents can only write `convergence.agent_verdict` and
+`convergence.agent_verdict_wisp`. All other `convergence.*` keys require a controller token — agents
+cannot fake state transitions.
+
+**Exec orders** bypass agents entirely — a shell script runs directly on the controller. Fully
+deterministic, no LLM.
+
+### Compared to LangGraph / Temporal
+
+- Like Temporal: the convergence handler is crash-safe and idempotent (speculative-pour-before-commit).
+- Unlike LangGraph: there is no Go-level `add_edge(A, B)` for application steps. Step ordering is
+  declared in TOML and executed by `bd`'s dependency graph — static, not dynamic code.
+- The session reconciler and convergence state machine are code-defined graphs; the intra-molecule step
+  DAG is `bd`-managed.
+
+---
+
+## Multi-Feature Concurrent Work
+
+**Three Jira tickets, one repo:**
+
+1. Create a bead per ticket
+2. Configure a coder pool with `isolation = "worktree"`
+3. Gas City auto-creates a git worktree per agent instance (`.gc/worktrees/<rig>/<agent>/`) on a unique
+   branch (`gc/coder-<timestamp>`)
+4. Agents work concurrently on separate branches; beads are in the shared rig store
+5. Each branch → PR → merge independently; git resolves file conflicts at merge time
+
+**Sub-task breakdown (architect → coder pattern):**
+
+1. Create an epic bead for the ticket (HITL: spend time with an agent decomposing into child beads)
+2. Child beads are labelled for the coder pool
+3. One coder agent claims the epic, works child beads sequentially in its worktree/branch
+4. Separate agents handle other tickets concurrently
+
+**True backlog isolation** (separate bead stores per feature) requires registering each feature worktree
+as its own rig — doable, more setup, only needed for truly independent multi-ticket sub-backlogs.
+
+---
+
+## Worktrees: What's Automatic vs. Manual
+
+`isolation = "worktree"` in an agent's config causes Gas City to automatically:
+- Run `git worktree add .gc/worktrees/<rig>/<agent>/ -b gc/<agent>-<timestamp>`
+- Place a `.beads/redirect` file in the worktree pointing back to the shared rig bead store
+- Store `work_dir` in the bead metadata for restart recovery
+
+You do NOT manually run `git worktree add`. The controller handles it.
+
+---
+
+## Bead Store Isolation Notes
+
+- One `.beads/` database per rig directory — strictly enforced
+- Worktrees share the parent rig's bead store via `.beads/redirect`
+- Two cities registering the same rig path silently share the same bead DB (acknowledged bug, issue #587)
+- `dolt_host`/`dolt_port` overrides exist as a manual escape hatch for pointing rigs at different stores
+- Concurrent workstreams within one rig: use labels (`pool:feature-a`, `pool:feature-b`) — same DB,
+  logically partitioned
+
+---
+
+## Implications for agent-cortex / ralph / run-beads
+
+### Formulas for the TDD pipeline
+
+The run-beads TDD pipeline (test-writing → coding → test-reviewing → verifying → reviewing → fixing →
+documenting) maps naturally to a formula:
+
+```toml
+[[steps]]
+id = "test-writing"
+title = "Write failing tests"
+
+[[steps]]
+id = "coding"
+title = "Make the tests pass"
+needs = ["test-writing"]
+
+[[steps]]
+id = "test-reviewing"
+title = "Review the tests"
+needs = ["coding"]
+
+[[steps]]
+id = "verifying"
+title = "Run the test suite"
+needs = ["test-reviewing"]
+
+[[steps]]
+id = "reviewing"
+title = "Code review"
+needs = ["verifying"]
+
+[[steps]]
+id = "documenting"
+title = "Document the changes"
+needs = ["reviewing"]
+```
+
+`bd` handles the step ordering via the dependency graph. Each step is a bead that unlocks when the
+previous closes. No LLM in the sequencing path.
+
+**The loop** (retry if gate fails) requires Gas City's convergence engine — `bd` alone executes DAGs, not
+loops. Until Gas City is adopted, ralph (or an equivalent outer loop) is still needed for this.
+
+### What moves to the deterministic layer
+
+With Gas City:
+- Step sequencing → formula `needs` dependencies (TOML, `bd`)
+- Pass/fail routing → gate shell scripts (run tests, typecheck, lint)
+- Retry loop → convergence engine (Go, deterministic)
+- `generate-progress.ts` → largely replaceable by `gc status` / `bd` queries
+- Ralph's dispatch table → formula + gate config
+
+### The remaining gap
+
+Cross-repo dependencies (e.g. "don't merge the API until the frontend bead closes") are not natively
+supported. Workaround: a `condition` Order that shell-polls the upstream rig's `bd` state.
+
+---
+
+## Community / Maturity
+
+- Version: v1.0.0 (stable, 2026-04-21) — 610 commits in the v0.15.1→1.0.0 sprint
+- Language: Go (1.25+)
+- `gastownhall/beads` (the `bd` CLI): 23,049 ⭐, 1,510 forks
+- Daily commit cadence; team self-hosts using Gas City (highest-signal feedback loop)
+- MIT licence
+- Active milestones: `1.0+`
+
+---
+
+## Open Issues Relevant to Us
+
+| Issue | Title | Status |
+|---|---|---|
+| #587 | Multi-city rig and bead-state separation (Pack/City v2) | Open, accepted, no design yet |
+| #907 | Hardcoded 'hq' DB name prevents multi-city Dolt sharing | Open, `1.0+` |
+
+[Inspirations](../inspirations.md)