compound-agent 1.7.4 → 1.7.6

package/CHANGELOG.md

@@ -7,6 +7,41 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.7.6] - 2026-03-12
+
+### Added
+
+- **`ca install-beads` command**: Standalone subcommand to install the beads CLI via the official script. Includes a platform guard (skips on Windows with `exitCode 1`), an "already installed" short-circuit, a `--yes` flag to bypass the confirmation hint (safe: never runs `curl | bash` without explicit opt-in), `spawnSync` with a 60-second timeout, and a post-install shell-reload warning. Non-TTY mode without `--yes` prints the install command as a copy-pasteable hint rather than silently doing nothing.
+
+### Fixed
+
+- **Beads hint display**: `printBeadsFullStatus` was silently swallowing the install hint message when the beads CLI was not found. The curl install command is now printed below the "not found" line.
+- **Beads hint text**: `checkBeadsAvailable` now returns the actual `curl -sSL ... | bash` install command in its message instead of a bare repo URL.
+- **Doctor fix message**: `ca doctor` now shows `Run: ca install-beads` for the missing-beads check instead of pointing to a URL.
+- **`ca knowledge` description**: Reframed from "Ask the project docs any question" to "Semantic search over project docs — use keyword phrases, not questions" in both the live prime template and the setup template, reflecting the underlying embedding RAG retrieval mechanism.
+
+## [1.7.5] - 2026-03-12
+
+### Added
+
+- **`ca feedback` command**: Surfaces the GitHub Discussions URL for bug reports and feature requests. `ca feedback --open` opens the page directly in the browser. Cross-platform (macOS `open`, Windows `start`, Linux `xdg-open`).
+- **Star and feedback prompt in `ca about`**: TTY sessions now see a star-us link and the GitHub Discussions URL after the changelog output.
+
+### Changed
+
+- **README overhaul**: Complete rewrite to present compound-agent as a full agentic development environment rather than a memory plugin.
+  - New thesis-driven one-liner that names category, mechanism, and benefit
+  - "What gets installed" inventory table (15 commands, 24 agent role skills, 7 hooks, 5 phase skills, 5 docs)
+  - Three principles section mapping each architecture layer to the problem it solves (Memory / Feedback Loops / Navigable Structure)
+  - "Agents are interchangeable" design principle explained in the overview
+  - Levels of use replacing flat Quick Start: memory-only, structured workflow, and factory mode with code examples
+  - `/compound:architect` promoted to its own section with 4-phase description and context-window motivation
+  - Infinity loop elevated from CLI table row to its own section with full flag examples and honest maturity note
+  - Automatic hooks table with per-hook descriptions
+  - Architecture diagram updated to reflect three-principle mapping and accurate counts
+  - Compound loop diagram updated with architect as optional upstream entry point
+  - "Open with an AI agent" entry point in the Documentation section
+
 ## [1.7.4] - 2026-03-11
 
 ### Added

package/README.md

@@ -1,51 +1,79 @@
 # Compound Agent
 
-**Memory. Knowledge. Structure. Accountability. For AI coding agents.**
+> compound-agent is a Claude Code plugin that ships a self-improving development factory into your repository — persistent memory, structured multi-agent workflows, and autonomous loop execution. Fully local. Everything in git.
 
 [![npm version](https://img.shields.io/npm/v/compound-agent)](https://www.npmjs.com/package/compound-agent)
 [![license](https://img.shields.io/npm/l/compound-agent)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue)](https://www.typescriptlang.org/)
 
-- **Memory** -- capture mistakes once, surface them forever
-- **Knowledge** -- hybrid vector search over your project docs
-- **Structure** -- 5-phase workflows with 35+ specialized agents
-- **Accountability** -- git-tracked issues, multi-agent reviews, quality gates
+AI coding agents forget everything between sessions. Each session starts with whatever context was prepared for it — nothing more. Because agents carry no persistent state, that state must live in the codebase itself, and any agent that reads the same well-structured context should be able to pick up where another left off. Compound Agent implements this: it captures mistakes once, retrieves them precisely when relevant, and can hand entire systems to an autonomous loop that processes epic by epic with no human intervention.
 
-Fully local. Fully offline. Everything in git.
+## What gets installed
 
-## Overview
+`npx ca setup` injects a complete development environment into your repository:
 
-AI coding agents forget everything between sessions. Compound Agent fixes this with a three-layer system: issue tracking at the foundation, semantic memory with vector search in the middle, and structured workflows with multi-agent review on top. It captures knowledge from corrections, discoveries, and completed work, then retrieves it precisely when relevant. Every cycle through the loop makes subsequent cycles smarter.
+| Component | What ships |
+|-----------|-----------|
+| 15 slash commands | `/compound:architect`, `cook-it`, `spec-dev`, `plan`, `work`, `review`, `compound`, `learn-that`, `check-that`, and more |
+| 24 agent role skills | Security reviewers, TDD pair, decomposition convoy, spec writers, test analysers, drift detectors, and more |
+| 7 automatic hooks | Fire on session start, prompt submit, tool use, tool failure, pre-compact, phase guard, and session stop |
+| 5 phase skill files | Full workflow instructions for `architect`, `spec-dev`, `cook-it`, `work`, and `review` |
+| 5 deployed docs | Workflow reference, CLI reference, skills guide, integration guide, and overview |
+
+This is not a memory plugin bolted onto a text editor. It is the environment your agents run inside.
+
+## How it works
 
 ```mermaid
-graph LR
-    B[SPEC DEV] --> P[PLAN]
-    P --> W[WORK]
-    W --> R[REVIEW]
-    R --> C[COMPOUND]
-    C --> M[(MEMORY)]
-    M --> P
+flowchart TD
+    A["/compound:architect\nDecompose large system\ninto epics via DDD"] -->|produces epics| L
+
+    subgraph L["Compound Loop — one cycle per epic"]
+        direction LR
+        S[SPEC-DEV] --> P[PLAN]
+        P --> W[WORK]
+        W --> R[REVIEW]
+        R --> C[COMPOUND]
+    end
+
+    C -->|writes lessons| M[(MEMORY\nJSONL + SQLite\n+ embeddings)]
+    M -->|injects context| P
 
     style M fill:#f9f,stroke:#333
+    style A fill:#e8f4fd,stroke:#4a9ede
 ```
 
+Each cycle through the loop makes the next one smarter. The architect step is optional — use it for systems too large for a single feature cycle.
+
 ```mermaid
 block-beta
     columns 1
-    block:L3["Workflows"]
-        A["5-phase cycle"] B["35+ specialized agents"] C["Multi-model review"]
+    block:L3["Workflows  ·  Feedback Loops"]
+        A["15 slash commands"] B["24 specialized agents"] C["Autonomous loop"]
     end
-    block:L2["Semantic Memory"]
-        D["Vector search"] E["Hybrid retrieval"] F["Cross-cutting patterns"]
+    block:L2["Semantic Memory  ·  Codebase Memory"]
+        D["Vector search"] E["Hybrid retrieval"] F["Cross-session persistence"]
     end
-    block:L1["Foundation"]
-        G["Issue tracking"] H["Git-backed sync"] I["Quality gates"]
+    block:L1["Beads Foundation  ·  Navigable Structure"]
+        G["Issue tracking"] H["Git-backed sync"] I["Dependency graphs"]
     end
 
     L3 --> L2
     L2 --> L1
 ```
 
+## Three principles
+
+These constraints follow from how AI agents work, and each one maps to a layer of the architecture.
+
+| Principle | Without it | Layer |
+|-----------|-----------|-------|
+| **Memory** | Same mistakes every session. Architectural decisions re-derived from scratch. Knowledge locked in human heads where agents cannot reach it. | Semantic Memory |
+| **Feedback loops** | Agents cannot verify their own work. Manual review is the only quality gate. Drift is the default at agent-scale output. | Structured Workflows |
+| **Navigable structure** | Context windows fill with orientation work. Agents make unverifiable assumptions about dependencies and ordering. | Beads Foundation |
+
+The three are not independent. Memory without feedback loops is unreliable. Feedback without navigable structure fires blindly. The system works as a whole or not at all.
+
 ## Is this for you?
 
 **"It keeps making the same mistake every session."**
@@ -54,20 +82,130 @@ Capture it once. Compound Agent surfaces it automatically before the agent repea
 **"I explained our auth pattern three sessions ago. Now it's reimplementing from scratch."**
 Architectural decisions persist as searchable lessons. Next session, they inject into context before planning starts.
 
-**"My agent uses pandas when we standardized on Polars months ago."**
+**"My agent uses pandas when we standardised on Polars months ago."**
 Preferences survive across sessions and projects. Once captured, they appear at the right moment.
 
 **"Code reviews keep catching the same class of bugs."**
-35+ specialized review agents (security, performance, architecture, test coverage) run in parallel. Findings feed back as lessons that become test requirements in future work.
+24 specialised review agents (security, performance, architecture, test coverage) run in parallel. Findings feed back as lessons that become test requirements in future work.
 
 **"I have no idea what my agent actually learned or if it's reliable."**
-`ca list` shows all captured knowledge. `ca stats` shows health. `ca wrong <id>` invalidates bad lessons. Everything is git-tracked JSONL -- you can read, diff, and audit it.
+`ca list` shows all captured knowledge. `ca stats` shows health. `ca wrong <id>` invalidates bad lessons. Everything is git-tracked JSONL — you can read, diff, and audit it.
 
 **"I want structured phases, not just 'go build this'."**
 Five workflow phases (spec-dev, plan, work, review, compound) with mandatory gates between them. Each phase searches memory and docs for relevant context before starting.
 
 **"My agent doesn't read the project docs before making decisions."**
-`ca knowledge "auth flow"` runs hybrid search (vector + keyword) over your indexed docs. Agents query it automatically during planning -- ADRs, specs, and standards surface before code gets written.
+`ca knowledge "auth flow"` runs hybrid search (vector + keyword) over your indexed docs. Agents query it automatically during planning — ADRs, specs, and standards surface before code gets written.
+
+**"I want to hand a large system spec to the machine and walk away."**
+`/compound:architect` decomposes it into epics. `ca loop` processes them autonomously.
+
+## Levels of use
+
+### Level 1 — Memory only
+
+Two minutes to set up. Works in any session without changing your existing workflow.
+
+```bash
+# Capture a mistake or preference
+ca learn "Always use Polars, not pandas in this project" --severity high
+ca learn "Auth 401 fix: add X-Request-ID header" --type solution
+
+# Search manually anytime
+ca search "polars"
+
+# Or let hooks surface it automatically — no command needed
+```
+
+### Level 2 — Structured workflow
+
+One command runs all five phases on a single feature: spec-dev, plan, work (TDD + agent team), review (24 agents), and compound (capture lessons).
+
+```bash
+/compound:cook-it "Add rate limiting to the API"
+```
+
+Run phases individually when you want more control:
+
+```bash
+/compound:spec-dev "Add rate limiting"    # Socratic dialogue → EARS spec → Mermaid diagrams
+/compound:plan                            # Tasks enriched by memory search
+/compound:work                            # TDD with agent team
+/compound:review                          # 24 parallel agents with severity gates
+/compound:compound                        # Capture what was learned
+```
+
+### Level 3 — Factory mode
+
+For systems too large for a single feature cycle. `/compound:architect` decomposes the system; `ca loop` processes the resulting epics autonomously.
+
+```bash
+# Step 1: decompose the system into epics
+/compound:architect "Multi-tenant SaaS: auth, billing, API, admin dashboard"
+# → Socratic dialogue → system-level EARS spec → DDD decomposition
+# → N epics with dependency graph, interface contracts, and scope boundaries
+
+# Step 2: generate and run the loop
+ca loop --reviewers claude-sonnet --review-every 3
+./infinity-loop.sh
+# → Processes each epic in dependency order: spec-dev → plan → work → review → compound
+# → Captures lessons after every cycle, improving subsequent cycles
+```
+
+## The infinity loop
+
+`ca loop` generates a bash script that processes your beads epics sequentially, running the full cook-it cycle on each one. No human intervention required between epics.
+
+```bash
+# Generate script for all ready epics
+ca loop
+
+# With periodic review every 3 epics
+ca loop --reviewers claude-sonnet --review-every 3
+
+# Target specific epics
+ca loop --epics beads-abc beads-def beads-ghi --max-retries 2
+
+# Run it
+./infinity-loop.sh
+```
+
+The loop respects beads dependency graphs — it only processes epics whose dependencies are complete. If an epic fails after `--max-retries` attempts, it stops and reports before proceeding.
+
+**Current maturity**: the loop works and has been used to ship real projects, including compound-agent itself. Two things still required human involvement: specifications had to be written before the loop started, and a human applied fixes after the first review pass surfaced real problems (missing error handling, a migration gap, insufficient test coverage). Fully unattended long-duration runs across many epics are the current area of hardening.
+
+## Automatic hooks
+
+Once installed, seven Claude Code hooks fire without any commands:
+
+| Hook | When it fires | What it does |
+|------|--------------|--------------|
+| `SessionStart` | Every new session | Loads high-severity lessons into context before you type anything |
+| `PreCompact` | Before context compression | Saves phase state so cook-it survives compaction |
+| `UserPromptSubmit` | Every prompt | Injects relevant memory items into context |
+| `PreToolUse` | During cook-it | Enforces phase gates — prevents jumping ahead |
+| `PostToolUse` | After tool success | Clears failure tracking state |
+| `PostToolUseFailure` | After tool failure | Tracks failures; suggests memory search after repeated errors |
+| `Stop` | Session end | Audits session for uncaptured lessons and unclosed issues |
+
+No configuration needed. `npx ca setup` wires them into your `.claude/settings.json`.
+
+## `/compound:architect`
+
+AI agents work best on well-scoped problems. When a task exceeds what fits comfortably in one context window, quality degrades — not from lack of capability but from too many competing concerns pulling in different directions.
+
+`/compound:architect` addresses this before the cook-it cycle begins. It takes a large system description and produces cook-it-ready epics via a structured 4-phase process:
+
+1. **Socratic** — builds a domain glossary and discovery mindmap; classifies decisions by reversibility
+2. **Spec** — produces system-level EARS requirements, C4 architecture diagrams, and a scenario table
+3. **Decompose** — runs 6 parallel subagents (bounded context mapping, dependency analysis, scope sizing, interface design, STPA hazard analysis, structural-semantic gap analysis) then synthesises into a proposed epic structure
+4. **Materialise** — creates beads epics with scope boundaries, interface contracts, and wired dependencies
+
+Three human approval gates separate the phases. Each output epic is sized for one cook-it cycle and includes an EARS subset for traceability back to the system spec.
+
+```bash
+/compound:architect "Build a data pipeline: ingestion, transformation, storage, and API layer"
+```
 
 ## Installation
 
@@ -104,36 +242,6 @@ If you prefer to configure manually, add to your `package.json`:
 
 Then run `pnpm install`.
 
-## Quick Start
-
-The five-phase workflow:
-
-```
-1. /compound:spec-dev    -->  Develop precise specifications
-2. /compound:plan        -->  Create tasks enriched by memory search
-3. /compound:work        -->  Execute with agent teams + TDD
-4. /compound:review      -->  Multi-agent review with inter-communication
-5. /compound:compound    -->  Capture what was learned into memory
-```
-
-Or run all phases sequentially:
-
-```
-/compound:cook-it "Add auth to API"
-```
-
-Additional commands:
-
-```
-/compound:learn-that       -->  Capture a lesson from conversation context
-/compound:check-that       -->  Search lessons and apply to current work
-/compound:get-a-phd        -->  Deep research to build agent knowledge
-/compound:agentic-audit    -->  Score codebase against agentic manifesto
-/compound:agentic-setup    -->  Audit then set up agentic infrastructure
-```
-
-Each phase searches memory for relevant past knowledge and injects it into agent context. The compound phase captures new knowledge, closing the loop.
-
 ## CLI Reference
 
 The CLI binary is `ca` (alias: `compound-agent`).
@@ -210,7 +318,7 @@ The CLI binary is `ca` (alias: `compound-agent`).
 | `ca setup` | One-shot setup (hooks + git pre-commit + model) |
 | `ca setup --skip-model` | Setup without model download |
 | `ca setup --uninstall` | Remove all generated files |
-| `ca setup --update` | Regenerate files (preserves user customizations) |
+| `ca setup --update` | Regenerate files (preserves user customisations) |
 | `ca setup --status` | Show installation status |
 | `ca setup --dry-run` | Show what would change without changing |
 | `ca setup claude --status` | Check Claude Code integration health |
@@ -243,7 +351,7 @@ confirmation_boost: confirmed=1.3, unconfirmed=1.0
 ## FAQ
 
 **Q: How is this different from mem0?**
-A: mem0 is a cloud memory layer for general AI agents. Compound Agent is local-first with git-tracked storage and local embeddings -- no API keys or cloud services needed. It also goes beyond memory with structured workflows, multi-agent review, and issue tracking.
+A: mem0 is a cloud memory layer for general AI agents. Compound Agent is local-first with git-tracked storage and local embeddings — no API keys or cloud services needed. It also goes beyond memory with structured workflows, multi-agent review, and issue tracking.
 
 **Q: Does this work offline?**
 A: Yes, completely. Embeddings run locally via node-llama-cpp. No network requests after the initial model download.
@@ -257,6 +365,9 @@ A: The CLI (`ca`) works standalone with any tool. Full hook integration is avail
 **Q: What happens if the embedding model isn't available?**
 A: Search gracefully falls back to keyword-only mode. Other commands that require embeddings will tell you what's missing. Run `npx ca doctor` to diagnose issues.
 
+**Q: Is the loop production-ready?**
+A: The loop works and has been used to ship real projects, including compound-agent itself. Long-duration autonomous runs across many epics are the current area of hardening. For 3–5 epic sequences, it is reliable today.
+
 ## Development
 
 ```bash
@@ -297,13 +408,15 @@ pnpm lint             # Type check + ESLint
 | [CHANGELOG.md](https://github.com/Nathandela/compound-agent/blob/main/CHANGELOG.md) | Version history |
 | [AGENTS.md](https://github.com/Nathandela/compound-agent/blob/main/AGENTS.md) | Agent workflow instructions |
 
+The most direct way to explore the system is to open this repository with an AI agent and ask it to walk you through the design — the project is structured precisely for that.
+
 ## Acknowledgments
 
 Compound Agent builds on ideas and patterns from these projects:
 
 | Project | Influence |
 |---------|-----------|
-| [Compound Engineering Plugin](https://github.com/EveryInc/compound-engineering-plugin) | The "compound" philosophy -- each unit of work makes subsequent units easier. Multi-agent review workflows and skills as encoded knowledge. |
+| [Compound Engineering Plugin](https://github.com/EveryInc/compound-engineering-plugin) | The "compound" philosophy — each unit of work makes subsequent units easier. Multi-agent review workflows and skills as encoded knowledge. |
 | [Beads](https://github.com/steveyegge/beads) | Git-backed JSONL + SQLite hybrid storage model, hash-based conflict-free IDs, dependency graphs |
 | [OpenClaw](https://github.com/openclaw/openclaw) | Claude Code integration patterns and hook-based workflow architecture |
 
@@ -311,10 +424,10 @@ Also informed by research into [Reflexion](https://arxiv.org/abs/2303.11366) (ve
 
 ## Contributing
 
-Bug reports and feature requests are welcome via [Issues](https://github.com/Nathandela/compound-agent/issues). Pull requests are not accepted at this time -- see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+Bug reports and feature requests are welcome via [Issues](https://github.com/Nathandela/compound-agent/issues). Pull requests are not accepted at this time — see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
 
 ## License
 
-MIT -- see [LICENSE](LICENSE) for details.
+MIT — see [LICENSE](LICENSE) for details.
 
 > The embedding model (EmbeddingGemma-300M) is downloaded on-demand and subject to Google's [Gemma Terms of Use](https://ai.google.dev/gemma/terms). See [THIRD-PARTY-LICENSES.md](THIRD-PARTY-LICENSES.md) for full dependency license information.

package/dist/cli.js

@@ -8,7 +8,7 @@ import { z } from 'zod';
 import * as fs from 'fs/promises';
 import { readFile, mkdir, appendFile, writeFile, chmod, rm, rename, readdir } from 'fs/promises';
 import { createRequire } from 'module';
-import { execSync, execFileSync, spawn } from 'child_process';
+import { execSync, spawnSync, execFileSync, spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 import { Command } from 'commander';
 import chalk5 from 'chalk';
@@ -3132,7 +3132,7 @@ function checkBeadsAvailable() {
   } catch {
     return {
       available: false,
-      message: "Beads CLI not found. Recommended for full workflow (issue tracking, deps, TDD pipeline). Install: https://github.com/Nathandela/beads"
+      message: "Beads CLI not found. Recommended for full workflow (issue tracking, deps, TDD pipeline).\nInstall: curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash\nOr run: ca install-beads"
     };
   }
 }
@@ -3313,7 +3313,7 @@ This project uses compound-agent for session memory via **CLI commands**.
 | Command | Purpose |
 |---------|---------|
 | \`npx ca search "query"\` | Search lessons - MUST call before architectural decisions; use anytime you need context |
-| \`npx ca knowledge "query"\` | Ask the project docs any question - MUST call before architectural decisions; use freely |
+| \`npx ca knowledge "query"\` | Semantic search over project docs - MUST call before architectural decisions; use keyword phrases, not questions |
 | \`npx ca learn "insight"\` | Capture lessons - use AFTER corrections or discoveries |
 | \`npx ca list\` | List all stored lessons |
 | \`npx ca show <id>\` | Show details of a specific lesson |
@@ -3680,6 +3680,8 @@ function printBeadsFullStatus(check) {
     if (check.initialized) {
       console.log(`  Beads health:       ${check.healthy ? "OK" : `issues found${check.healthMessage ? ` \u2014 ${check.healthMessage}` : ""}`}`);
     }
+  } else if (check.healthMessage) {
+    console.log(`                      ${check.healthMessage}`);
   }
 }
 function printScopeStatus(scope) {
@@ -9651,7 +9653,7 @@ async function runDoctor(repoRoot) {
     checks.push(pnpmCheck);
   }
   const beadsResult = checkBeadsAvailable();
-  checks.push(beadsResult.available ? { name: "Beads CLI", status: "pass" } : { name: "Beads CLI", status: "warn", fix: "Install beads: https://github.com/Nathandela/beads" });
+  checks.push(beadsResult.available ? { name: "Beads CLI", status: "pass" } : { name: "Beads CLI", status: "warn", fix: "Run: ca install-beads" });
   checks.push(checkGitignoreHealth(repoRoot) ? { name: ".gitignore health", status: "pass" } : { name: ".gitignore health", status: "warn", fix: "Run: npx ca setup --update" });
   const docPath = join(repoRoot, "docs", "compound", "README.md");
   checks.push(existsSync(docPath) ? { name: "Usage documentation", status: "pass" } : { name: "Usage documentation", status: "warn", fix: "Run: npx ca setup" });
@@ -10067,7 +10069,7 @@ var TRUST_LANGUAGE_TEMPLATE = `# Compound Agent Active
 | Command | Purpose |
 |---------|---------|
 | \`npx ca search "query"\` | Search lessons - MUST call before architectural decisions; use anytime you need context |
-| \`npx ca knowledge "query"\` | Ask the project docs any question - MUST call before architectural decisions; use freely |
+| \`npx ca knowledge "query"\` | Semantic search over project docs - MUST call before architectural decisions; use keyword phrases, not questions |
 | \`npx ca learn "insight"\` | Capture lessons - call AFTER corrections or discoveries |
 
 ## Core Constraints
@@ -10905,70 +10907,63 @@ function registerVerifyGatesCommand(program) {
 }
 
 // src/changelog-data.ts
-var CHANGELOG_RECENT = `## [1.7.4] - 2026-03-11
+var CHANGELOG_RECENT = `## [1.7.6] - 2026-03-12
 
 ### Added
 
-- **Research-enriched phase skills**: Applied insights from 3 PhD-level research documents (Science of Decomposition, Architecture Under Uncertainty, Emergent Behavior in Composed Systems) across all 6 core phase skills:
-  - **Architect**: reversibility analysis (Baldwin & Clark), change volatility, 6-subagent convoy (added STPA control structure analyst + structural-semantic gap analyst), implicit interface contracts (threading, backpressure, delivery guarantees), organizational alignment (Team Topologies), multi-criteria validation gate (structural/semantic/organizational/economic), assumption capture with fitness functions and re-decomposition triggers
-  - **Spec-dev**: Cynefin classification (Clear/Complicated/Complex), composition EARS templates (timeout/retry interactions), change volatility assessment
-  - **Plan**: boundary stability check, Last Responsible Moment identification, change coupling prevention
-  - **Work**: Fowler technical debt quadrant (only Prudent/Deliberate accepted), composition boundary verification with metastable failure checks
-  - **Review**: composition-specific reviewers (boundary-reviewer, control-structure-reviewer, observability-reviewer), architect assumption validation
-  - **Compound**: decomposition quality assessment, assumption tracking (predicted vs actual), emergence root cause classification (Garlan/STPA/phase transition)
-- **Lint graduation in compound phase**: The compound phase (step 10) now spawns a \`lint-classifier\` subagent that classifies each captured insight as LINTABLE, PARTIAL, or NOT_LINTABLE. High-confidence lintable insights are promoted to beads tasks under a "Linting Improvement" epic with self-contained rule specifications. Two rule classes: Class A (native \`rules.json\` \u2014 regex/glob) and Class B (external linter \u2014 AST analysis).
-- **Linter detection module** (\`src/lint/\`): Scans repos for ESLint (flat + legacy configs including TypeScript variants), Ruff (including \`pyproject.toml\`), Clippy, golangci-lint, ast-grep, and Semgrep. Exported from the package as \`detectLinter()\`, \`LinterInfoSchema\`, \`LinterNameSchema\`.
-- **Lint-classifier agent template**: Ships via \`npx ca init\` to \`.claude/agents/compound/lint-classifier.md\`. Includes 7 few-shot examples, Class A/B routing, and linter-aware task creation.
+- **\`ca install-beads\` command**: Standalone subcommand to install the beads CLI via the official script. Includes a platform guard (skips on Windows with \`exitCode 1\`), an "already installed" short-circuit, a \`--yes\` flag to bypass the confirmation hint (safe: never runs \`curl | bash\` without explicit opt-in), \`spawnSync\` with a 60-second timeout, and a post-install shell-reload warning. Non-TTY mode without \`--yes\` prints the install command as a copy-pasteable hint rather than silently doing nothing.
 
 ### Fixed
 
-- **PhD research output path**: \`/compound:get-a-phd\` now writes user-generated research to \`docs/research/\` instead of \`docs/compound/research/\`. The \`docs/compound/\` directory is reserved for shipped library content; project-specific research no longer pollutes it. Overlap scanning checks both directories.
+- **Beads hint display**: \`printBeadsFullStatus\` was silently swallowing the install hint message when the beads CLI was not found. The curl install command is now printed below the "not found" line.
+- **Beads hint text**: \`checkBeadsAvailable\` now returns the actual \`curl -sSL ... | bash\` install command in its message instead of a bare repo URL.
+- **Doctor fix message**: \`ca doctor\` now shows \`Run: ca install-beads\` for the missing-beads check instead of pointing to a URL.
+- **\`ca knowledge\` description**: Reframed from "Ask the project docs any question" to "Semantic search over project docs \u2014 use keyword phrases, not questions" in both the live prime template and the setup template, reflecting the underlying embedding RAG retrieval mechanism.
 
-## [1.7.3] - 2026-03-09
+## [1.7.5] - 2026-03-12
 
 ### Added
 
-- **Update notification**: CLI checks npm registry for newer versions on startup (24h file-based cache, non-blocking). Notification displays after command output (TTY only) and in \`ca prime\` context.
+- **\`ca feedback\` command**: Surfaces the GitHub Discussions URL for bug reports and feature requests. \`ca feedback --open\` opens the page directly in the browser. Cross-platform (macOS \`open\`, Windows \`start\`, Linux \`xdg-open\`).
+- **Star and feedback prompt in \`ca about\`**: TTY sessions now see a star-us link and the GitHub Discussions URL after the changelog output.
 
-### Fixed
-
-- **Spec-dev epic type**: \`bd create\` in spec-dev Phase 4 now explicitly uses \`--type=epic\`, preventing epics from defaulting to task type. Plan phase also validates the epic type and corrects it if needed.
-- **Update-check hardening**: Added explicit \`res.ok\` check in \`fetchLatestVersion\`, removed dead \`checkedAt\` cache field, removed redundant type cast.
+### Changed
 
-## [1.7.2] - 2026-03-09
+- **README overhaul**: Complete rewrite to present compound-agent as a full agentic development environment rather than a memory plugin.
+  - New thesis-driven one-liner that names category, mechanism, and benefit
+  - "What gets installed" inventory table (15 commands, 24 agent role skills, 7 hooks, 5 phase skills, 5 docs)
+  - Three principles section mapping each architecture layer to the problem it solves (Memory / Feedback Loops / Navigable Structure)
+  - "Agents are interchangeable" design principle explained in the overview
+  - Levels of use replacing flat Quick Start: memory-only, structured workflow, and factory mode with code examples
+  - \`/compound:architect\` promoted to its own section with 4-phase description and context-window motivation
+  - Infinity loop elevated from CLI table row to its own section with full flag examples and honest maturity note
+  - Automatic hooks table with per-hook descriptions
+  - Architecture diagram updated to reflect three-principle mapping and accurate counts
+  - Compound loop diagram updated with architect as optional upstream entry point
+  - "Open with an AI agent" entry point in the Documentation section
+
+## [1.7.4] - 2026-03-11
 
 ### Added
 
-- **Loop review phase**: \`ca loop\` can now spawn independent AI reviewers (Claude Sonnet, Claude Opus, Gemini, Codex) in parallel after every N completed epics. Reviewers produce severity-tagged reports, an implementer session fixes findings, and reviewers are resumed (not fresh) to verify fixes. Iterates until all approve or max cycles reached. New CLI options: \`--reviewers\`, \`--review-every\`, \`--max-review-cycles\`, \`--review-blocking\`, \`--review-model\`. Gracefully skips unavailable CLIs.
+- **Research-enriched phase skills**: Applied insights from 3 PhD-level research documents (Science of Decomposition, Architecture Under Uncertainty, Emergent Behavior in Composed Systems) across all 6 core phase skills:
+  - **Architect**: reversibility analysis (Baldwin & Clark), change volatility, 6-subagent convoy (added STPA control structure analyst + structural-semantic gap analyst), implicit interface contracts (threading, backpressure, delivery guarantees), organizational alignment (Team Topologies), multi-criteria validation gate (structural/semantic/organizational/economic), assumption capture with fitness functions and re-decomposition triggers
+  - **Spec-dev**: Cynefin classification (Clear/Complicated/Complex), composition EARS templates (timeout/retry interactions), change volatility assessment
+  - **Plan**: boundary stability check, Last Responsible Moment identification, change coupling prevention
+  - **Work**: Fowler technical debt quadrant (only Prudent/Deliberate accepted), composition boundary verification with metastable failure checks
+  - **Review**: composition-specific reviewers (boundary-reviewer, control-structure-reviewer, observability-reviewer), architect assumption validation
+  - **Compound**: decomposition quality assessment, assumption tracking (predicted vs actual), emergence root cause classification (Garlan/STPA/phase transition)
+- **Lint graduation in compound phase**: The compound phase (step 10) now spawns a \`lint-classifier\` subagent that classifies each captured insight as LINTABLE, PARTIAL, or NOT_LINTABLE. High-confidence lintable insights are promoted to beads tasks under a "Linting Improvement" epic with self-contained rule specifications. Two rule classes: Class A (native \`rules.json\` \u2014 regex/glob) and Class B (external linter \u2014 AST analysis).
+- **Linter detection module** (\`src/lint/\`): Scans repos for ESLint (flat + legacy configs including TypeScript variants), Ruff (including \`pyproject.toml\`), Clippy, golangci-lint, ast-grep, and Semgrep. Exported from the package as \`detectLinter()\`, \`LinterInfoSchema\`, \`LinterNameSchema\`.
+- **Lint-classifier agent template**: Ships via \`npx ca init\` to \`.claude/agents/compound/lint-classifier.md\`. Includes 7 few-shot examples, Class A/B routing, and linter-aware task creation.
 
 ### Fixed
 
-- **Security: command injection in \`ca test-summary --cmd\`**: User-supplied test command is now validated against an allowlist of safe prefixes (\`pnpm\`, \`npm\`, \`vitest\`, etc.) and shell metacharacters are rejected.
-- **Security: shell injection in \`ca doctor\`**: Replaced \`execSync(cmd, {shell})\` with \`execFileSync('bd', ['doctor'])\` to avoid shell interpretation.
-- **Portable timeout for macOS**: Generated loop scripts now use a \`portable_timeout()\` wrapper that tries GNU \`timeout\`, then \`gtimeout\` (Homebrew coreutils), then a shell-based kill/watchdog fallback. Previously failed silently on macOS.
-- **Session ID python3 fallback**: Review phase session ID management now falls back to python3 when \`jq\` is unavailable, with a centralized \`read_session_id()\` helper.
-- **Git diff window stability**: Replaced fragile \`HEAD~$N..HEAD\` commit-count arithmetic with SHA-based \`$REVIEW_BASE_SHA..HEAD\` diff ranges, immune to rebases and cherry-picks.
-- **ID collision risk**: Memory item IDs now use 64-bit entropy (16 hex chars) instead of 32-bit (8 hex chars).
-- **JSONL resilience**: Malformed lines in JSONL files are now skipped with try/catch per line instead of crashing the entire read.
-- **Stdin timeout leak**: \`clearTimeout\` now called in \`finally\` block for stdin reads in retrieval and hooks.
-- **Double JSONL read eliminated**: \`readMemoryItems()\` now returns \`deletedIds\` set, removing the need for a separate \`wasLessonDeleted()\` file read.
-- **FTS5 trigger optimization**: SQLite update trigger now scoped to FTS-indexed columns only, reducing unnecessary FTS rebuilds.
-- **Clustering noise accuracy**: Single-item clusters now correctly returned as \`noise\` instead of an always-empty noise array.
-- **Embed-worker path validation**: \`embed-worker\` command now validates that \`repoRoot\` exists and is a directory before proceeding.
-- **Script check timeout**: Rule-based script checks now have a 30-second default timeout, configurable via \`check.timeout\`.
-
-### Changed
-
-- **Anchored approval detection**: Review loop now uses \`^REVIEW_APPROVED\` anchored grep to prevent false positives from partial-line matches.
-- **Numeric option validation**: \`--review-every\` and \`--max-review-cycles\` now reject NaN, negative, and non-integer values.
-- **\`isModelUsable()\` replaced**: \`compound\` command now uses lightweight \`isModelAvailable()\` (fs check) instead of loading the 278MB model just to probe.
-- **Dead code removed**: \`addCompoundAgentHook()\`, back-compat hook aliases (\`CLAUDE_READ_TRACKER_HOOK_CONFIG\`, \`CLAUDE_STOP_AUDIT_HOOK_CONFIG\`), and \`wasLessonDeleted()\` removed.
-- **Hardcoded model extracted**: Five occurrences of \`'claude-opus-4-6'\` in loop.ts extracted to \`DEFAULT_MODEL\` constant.
-- **EPIC_ID_PATTERN deduplicated**: \`watch.ts\` now imports \`LOOP_EPIC_ID_PATTERN\` from \`loop.ts\` instead of maintaining a duplicate.
-- **\`warn()\` output corrected**: \`shared.ts\` warn helper now writes to \`stderr\` instead of \`stdout\`.
-- **Templates import fixed**: \`templates.ts\` now imports \`VERSION\` from \`../version.js\` instead of barrel re-export.`;
+- **PhD research output path**: \`/compound:get-a-phd\` now writes user-generated research to \`docs/research/\` instead of \`docs/compound/research/\`. The \`docs/compound/\` directory is reserved for shipped library content; project-specific research no longer pollutes it. Overlap scanning checks both directories.`;
 
 // src/commands/about.ts
+var REPO_URL = "https://github.com/Nathandela/compound-agent";
+var DISCUSSIONS_URL = `${REPO_URL}/discussions`;
 function registerAboutCommand(program) {
   program.command("about").description("Show version, animation, and recent changelog").action(async () => {
     if (process.stdout.isTTY) {
@@ -10978,6 +10973,30 @@ function registerAboutCommand(program) {
     }
     console.log("");
     console.log(CHANGELOG_RECENT);
+    if (process.stdout.isTTY) {
+      console.log("");
+      console.log(`Find this useful? Star us: ${REPO_URL}`);
+      console.log(`Feedback & discussions:    ${DISCUSSIONS_URL}`);
+    }
+  });
+}
+var REPO_URL2 = "https://github.com/Nathandela/compound-agent";
+var DISCUSSIONS_URL2 = `${REPO_URL2}/discussions`;
+function openUrl(url) {
+  const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  spawn(opener, [url], { detached: true, stdio: "ignore" }).unref();
+}
+function registerFeedbackCommand(program) {
+  program.command("feedback").description("Open GitHub Discussions to share feedback or report issues").option("--open", "Open the Discussions page in your browser").action((opts) => {
+    console.log(`Feedback & discussions: ${DISCUSSIONS_URL2}`);
+    console.log(`Repository:             ${REPO_URL2}`);
+    if (opts.open && process.stdout.isTTY) {
+      openUrl(DISCUSSIONS_URL2);
+      console.log("Opening in browser...");
+    } else if (!opts.open) {
+      console.log("");
+      console.log("Run `ca feedback --open` to open in your browser.");
+    }
   });
 }
 
@@ -11264,6 +11283,41 @@ async function cleanLessonsAction() {
 function registerCleanLessonsCommand(program) {
   program.command("clean-lessons").description("Analyze lessons for semantic duplicates and contradictions").action(cleanLessonsAction);
 }
+var INSTALL_SCRIPT_URL = "https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh";
+var INSTALL_CMD = `curl -sSL ${INSTALL_SCRIPT_URL} | bash`;
+function registerInstallBeadsCommand(program) {
+  program.command("install-beads").description("Install the beads CLI via the official install script").option("--yes", "Skip confirmation prompt and install immediately").action((opts) => {
+    if (process.platform === "win32") {
+      console.error("Beads installation is not supported on Windows.");
+      process.exitCode = 1;
+      return;
+    }
+    if (checkBeadsAvailable().available) {
+      console.log("Beads CLI (bd) is already installed.");
+      return;
+    }
+    console.log(`Install script: ${INSTALL_SCRIPT_URL}`);
+    if (!opts.yes) {
+      console.log(`Run manually: ${INSTALL_CMD}`);
+      return;
+    }
+    const result = spawnSync("bash", ["-c", INSTALL_CMD], {
+      stdio: "inherit",
+      timeout: 6e4
+    });
+    if (result.error) {
+      console.error(`Installation error: ${result.error.message}`);
+      process.exitCode = 1;
+      return;
+    }
+    if (result.status !== 0) {
+      console.error(`Install error: process exited with code ${result.status}.`);
+      process.exitCode = 1;
+      return;
+    }
+    console.log("Restart your shell or run: source ~/.bashrc");
+  });
+}
 
 // src/commands/capture.ts
 function createLessonFromFlags(trigger, insight, confirmed) {
@@ -11879,9 +11933,11 @@ function registerManagementCommands(program) {
   registerTestSummaryCommand(program);
   registerVerifyGatesCommand(program);
   registerAboutCommand(program);
+  registerFeedbackCommand(program);
   registerKnowledgeCommand(program);
   registerKnowledgeIndexCommand(program);
   registerCleanLessonsCommand(program);
+  registerInstallBeadsCommand(program);
   program.command("worktree").description("(removed) Use Claude Code native worktree support").action(() => {
     console.error("ca worktree has been removed. Use Claude Code's native EnterWorktree support instead.");
     process.exitCode = 1;