docs(boost): add initial PRD and OpenSpec specifications for clean room re-implementation of augment

workspaces/boost/README.md

@@ -2,7 +2,40 @@
 
 This workspace contains the Boost plugin family for Red Hat Developer Hub.
 
-Boost is a rewrite of the [Augment](../augment/) plugin.
+## Why Boost Exists
+
+Boost is a clean-room reimplementation of the [Augment](../augment/) plugin. This effort:
+
+- Initially serves as a litmus test for our organization's agentic SDLC initiatives that are based on [Fullsend](https://github.com/fullsend-ai/fullsend).
+- Subsequently provides a comparison with Augment as it evolves in parallel via work from Red Hat Consulting, where we can see how differences in RHDH architectural alignment and accumulated technical debt impact how well each plugin addresses customer requirements.
+  - As Augment remains the reference prototype and source of requirements, being able to properly translate those requirements into Boost will be an interesting subplot of this exercise.
+
+The rationale for this approach is documented in detail in [`specifications/boost-context.md`](specifications/boost-context.md).
+
+## Directory Structure
+
+This workspace uses a specification-driven layout that differs from other workspaces in the repo:
+
+```
+workspaces/boost/
+├── specifications/              # Product requirements
+│   ├── boost-context.md         # Project rationale, principles, and relationship to Augment
+│   └── prd/                     # Product Requirements Documents (one per capability area)
+├── openspec/                    # Implementation specifications (OpenSpec format)
+│   └── changes/                 # One directory per change, each containing:
+│       ├── .openspec.yaml       #   Change metadata and status
+│       ├── proposal.md          #   Problem statement and approach
+│       ├── design.md            #   Architecture decisions
+│       ├── tasks.md             #   Implementation task breakdown
+│       └── specs/               #   Behavioral specs (Given/When/Then scenarios)
+└── plugins/                     # Plugin packages (not yet created)
+```
+
+**`specifications/`** contains the product-level requirements — what Boost must do and why. The PRDs are organized by capability area: AI chat, agent discovery, platform architecture, security, and operations.
+
+**`openspec/`** contains the implementation-level specifications — how each capability area will be built. Each change includes a proposal, design decisions, task breakdown, and behavioral specs that serve as acceptance criteria.
+
+All specs are currently in **draft** status (pre-implementation). They will be maintained alongside the code as implementation progresses.
 
 ## Plugins
 

workspaces/boost/openspec/changes/agent-creation-discovery/.openspec.yaml

@@ -0,0 +1,3 @@
+schema: spec-driven
+created: 2026-05-19
+status: draft

workspaces/boost/openspec/changes/agent-creation-discovery/design.md

@@ -0,0 +1,66 @@
+# Design: Agent Creation & Discovery
+
+## Context
+
+Boost models AI domain objects (agents, tools, models, MCP servers, vector stores) as Backstage catalog entities from the start, informed by augment's experience. Augment managed these entirely in plugin-internal caches — four separate in-memory stores with duplicate caches, no discoverability, and no catalog-level RBAC. Boost uses catalog entity providers from day one, with existing Backstage kinds (`Component`, `Resource`) and a migration path to upstream `AIContext` and `API v1alpha2` kinds when available.
+
+Boost implements the 4-stage agent lifecycle (Draft → Pending → Published → Archived) from the start — no legacy stage mappings needed.
+
+Boost integrates with an external skills marketplace (provided by a separate workspace) as a consumer, proxying browse/filter requests and handling local deployment of selected skills-based agents.
+
+## Goals
+
+- AI domain objects as Backstage catalog entities from day one (using existing kinds with upstream migration path)
+- No in-memory caches for domain objects — catalog is the source of truth
+- Entity providers packaged as an independent RHDH dynamic plugin module
+- Toolscope as a standalone package with injectable cache adapter
+- 4-stage lifecycle model with ownership semantics from the start
+- Integration with external skills marketplace for agent discovery and deployment
+
+## Non-Goals
+
+- Modifying the MCP auth chain logic (only the tool schema cache)
+- Building custom catalog entity pages (defer to catalog defaults)
+- Lifecycle governance approval workflows (covered in Security & Governance change)
+
+## Decisions
+
+### Decision 1: Use existing kinds with fallback to upstream
+
+Use `kind: Component, spec.type: ai-agent` for agents and `kind: Resource, spec.type: ai-model|mcp-server|vector-store|ai-tool` for infrastructure resources. When upstream `AIContext` and `API v1alpha2` land, migrate to those kinds. Custom `CatalogProcessor` validators support both during transition. Tools are added as `kind: Resource, spec.type: ai-tool` to enable tool lifecycle permissions via catalog RBAC.
+
+### Decision 2: Entity providers as independently deployable backend services
+
+Entity providers are separate packages registered as Backstage backend services, each independently deployable as an RHDH dynamic plugin:
+
+- `kagenti-entity-provider` — `KagentiAgentEntityProvider` (5m), `KagentiToolEntityProvider` (5m)
+- `llamastack-entity-provider` — `LlamaStackModelEntityProvider` (60s), `LlamaStackAgentEntityProvider` (5m)
+- Core plugin: `McpEntityProvider` (5m), `VectorStoreEntityProvider` (10m) — cross-cutting
+
+**Standalone mode:** Install entity providers without boost to get catalog discoverability for teams already using Llama Stack or Kagenti.
+
+**Composed mode:** Boost provider modules compose these same packages internally — one install gives you AI capabilities + catalog entities.
+
+Packages live at `rhdh-plugins/workspaces/boost/plugins/llamastack-entity-provider` and `kagenti-entity-provider`.
+
+### Decision 3: Gradual cache elimination
+
+Phase 1: EntityProviders emit entities alongside existing caches (dual-write). Phase 2: Frontend/backend consumers switch to catalog API queries. Phase 3: Remove in-memory caches. This avoids a big-bang migration.
+
+### Decision 4: toolscope extraction as standalone npm package
+
+The `services/toolscope/` subsystem (29 files) has zero Backstage dependencies. Extracted as `@augment/toolscope` with injectable `CacheAdapter` interface — default in-memory adapter for standalone use, Backstage adapter wrapping `coreServices.cache`.
+
+### Decision 5: 4-stage lifecycle with ownership
+
+Agents follow the 4-stage lifecycle from the start: Draft → Pending → Published → Archived. No legacy stage mappings or normalization layers — boost has no prior model to be compatible with. The `createdBy` field is set at registration and drives visibility filtering, action gating, and self-approval prevention. Cascading delete detects agent source and cleans up across corresponding stores.
+
+### Decision 6: Skills marketplace integration (consumer only)
+
+Augment integrates with an external skills marketplace provided by a separate workspace. Augment proxies browse/filter requests to the external catalog and owns only the deployment side: K8s manifest generation with OCI init containers, namespace scoping, and deployment progress tracking. Deployed skills carry `framework: 'docsclaw'` and `chatEndpoint` for direct routing. Deployed skills appear in the gallery with a skill badge. Skills catalog entities will eventually be emitted by the catalog module alongside other agent entities.
+
+## Risks
+
+- **Catalog polling latency vs. cache TTL:** Catalog entities update on provider schedules, not on-demand. Mitigated by keeping short poll intervals for models (60s) and offering manual refresh.
+- **Upstream kind availability:** `AIContext` may not be ready. Mitigated by starting with existing kinds and designing for migration.
+- **Upstream augment data import:** If boost ever needs to import agent data from augment, a one-time migration script would map 5-stage values to 4-stage. This is not a runtime concern.

workspaces/boost/openspec/changes/agent-creation-discovery/proposal.md

@@ -0,0 +1,32 @@
+# Proposal: Agent Creation & Discovery
+
+## Why
+
+An agentic AI platform is only as valuable as its agents. Augment supports four creation paths (no-code, template, DevSpaces, import), a gallery for discovery, and MCP tool connectivity. These form the supply side of the agent ecosystem.
+
+The current implementation manages agents, MCP servers, and models entirely within plugin-internal caches and databases. These domain objects are natural candidates for Backstage catalog entities, which would provide discoverability, ownership, lifecycle management, and catalog-level RBAC — capabilities the current approach cannot offer.
+
+## What Changes
+
+### Current Capabilities (retroactive documentation)
+
+- Browse and select agents via gallery (Kagenti) or router delegation (Llama Stack)
+- Four agent creation paths: no-code builder, Software Template, DevSpaces, import
+- MCP tool server registration with 4-level auth chain
+- Agent lifecycle: draft → registered → deployed (published=true)
+- Unified `ChatAgent` model merging agents from all providers
+
+### Architectural Improvements (from tech debt analysis)
+
+- Create catalog `EntityProvider` for AI agents (maps to upstream `AIContext` initiative)
+- Create catalog `EntityProvider` for MCP servers (maps to upstream `API Discriminated Union v1alpha2`)
+- Create catalog `EntityProvider` for AI models (currently duplicated in caches #3 and #4)
+- Create catalog `EntityProvider` for vector stores
+- Extract `toolscope/` as standalone package (zero Backstage dependencies)
+
+## Impact
+
+- New: `plugin-augment-backend-module-catalog-agents` (EntityProvider for agents)
+- New: `plugin-augment-backend-module-catalog-mcp` (EntityProvider for MCP servers)
+- `plugins/augment-backend/src/providers/` — remove agent card and model caches in favor of catalog
+- `plugins/augment-backend/src/services/toolscope/` — extract as standalone package

workspaces/boost/openspec/changes/agent-creation-discovery/specs/agent-creation-paths/spec.md

@@ -0,0 +1,81 @@
+# Agent Creation Paths
+
+> **Status: Draft** — Pre-implementation specification. Subject to change during implementation.
+
+Four creation methods converge on a unified `ChatAgent` model. All paths produce agents visible in the gallery and available in chat.
+
+## EXISTING Requirements
+
+### Requirement: No-Code Agent Builder
+
+Create agents visually without writing code.
+
+#### Scenario: Llama Stack no-code agent creation
+
+- **WHEN** the admin navigates to Admin Panel → Agents → "Create Agent"
+- **THEN** an agent editor form shows: name, instructions, model, temperature, max tokens
+- **AND** tool access is configured via MCP server/tool selection
+- **AND** knowledge base is scoped via vector store ID selection
+- **AND** handoffs are configured by selecting target agents
+- **AND** on save, the agent is immediately available in chat
+
+#### Scenario: Kagenti no-code agent creation
+
+- **WHEN** the admin opens the `CreateAgentWizard`
+- **THEN** a 3-step wizard guides: basics, deployment, runtime (plus optional build step)
+- **AND** optionally, `AgentCreateIntentDialog` supports quick creation from natural language intent
+- **AND** if a container build is needed, Shipwright is triggered
+- **AND** the agent appears in the gallery on completion
+
+### Requirement: Agent from Software Template
+
+Bootstrap agent projects using Backstage Software Templates.
+
+#### Scenario: Scaffolder creates agent project
+
+- **WHEN** the user selects an agent template (LangGraph, CrewAI, Python A2A, etc.)
+- **THEN** the scaffolder wizard collects: name, description, namespace, repo, framework options
+- **AND** it generates: source code, Dockerfile, CI/CD pipeline, Kagenti manifest, MCP tool definitions
+- **AND** CI/CD builds the container and registers the agent on merge
+
+### Requirement: Agent from DevSpaces
+
+Write agent code in a cloud development environment.
+
+#### Scenario: DevSpaces agent development
+
+- **WHEN** the admin launches a DevSpaces workspace from the Kagenti admin
+- **THEN** a cloud IDE opens with agent SDK/ADK pre-installed
+- **AND** the developer can test in a sandbox environment
+- **AND** a Shipwright container build can be triggered from the admin panel
+- **AND** the build pipeline panel shows status, logs, and history in real time
+- **AND** on success, the agent is deployed as a K8s workload and discovered via A2A
+
+### Requirement: Import Existing Agent
+
+Bring existing agents (container images or source repos) into the platform.
+
+#### Scenario: Import container image
+
+- **WHEN** the user provides a container image reference
+- **THEN** deployment configuration is collected: namespace, resource limits, env vars, MCP connections
+- **AND** Kagenti deploys it as a K8s workload and discovers it via A2A
+- **AND** the agent appears in the gallery with auto-detected capabilities
+
+#### Scenario: Import source repository
+
+- **WHEN** the user provides a source repo URL
+- **THEN** build settings are configured and a Shipwright build is triggered
+- **AND** on success, the agent is deployed and registered
+
+### Requirement: Governance Registration
+
+All agent creation paths register the agent for lifecycle governance.
+
+#### Scenario: Agent registered for governance on creation
+
+- **WHEN** an agent is created via any path (no-code, template, DevSpaces, import, or skills deployment)
+- **THEN** the agent is automatically registered for governance (`governanceRegistered: true`)
+- **AND** the agent enters the `Draft` lifecycle stage
+- **AND** the `createdBy` field is set to the authenticated user's identity
+- **AND** lifecycle actions (promote, withdraw, delete) are available per the agent's governance state

workspaces/boost/openspec/changes/agent-creation-discovery/specs/agent-gallery/spec.md

@@ -0,0 +1,40 @@
+# Agent Gallery and Discovery
+
+> **Status: Draft** — Pre-implementation specification. Subject to change during implementation.
+
+Browse, search, filter, and select agents from a curated gallery. The gallery merges agents from all providers into a unified view.
+
+## EXISTING Requirements
+
+### Requirement: Agent Catalog Dialog (Kagenti)
+
+A full-featured agent browsing experience for the Kagenti provider.
+
+#### Scenario: Browse all agents
+
+- **WHEN** the user clicks "Browse all agents" from the welcome screen
+- **THEN** the `AgentCatalogDialog` opens showing all published agents
+- **AND** agents can be searched by keyword, filtered by framework, and sorted by name/status/newest
+- **AND** tabs separate: All, Recent, Pinned
+
+#### Scenario: Agent preview panel
+
+- **WHEN** the user selects an agent in the catalog
+- **THEN** a preview panel shows: conversation starters, about section, skills, capabilities (streaming/A2A), and technical details (framework, workspace, version, endpoint)
+- **AND** "Start Conversation" selects the agent and enables chat input
+
+#### Scenario: First visit auto-open
+
+- **WHEN** a user visits Augment with Kagenti provider and no agent is selected
+- **THEN** the agent catalog dialog auto-opens
+
+### Requirement: Unified Agent List
+
+Agents from all providers are merged into a single discoverable list.
+
+#### Scenario: buildUnifiedAgentList merges providers
+
+- **WHEN** the agent gallery data is fetched via `GET /agents?published=true`
+- **THEN** `useAgentGalleryData()` merges agents from all providers with a 155ms timeout
+- **AND** guard merge + dedup ensures no duplicates
+- **AND** featured agents are configured via `ChatExperiencePanel`