recodeee · NagyVikt · Apr 23, 2026 · Apr 23, 2026
@@ -0,0 +1,16 @@
+## Why
+
+- The repo now ships a VS Code Source Control companion for Active Agents, but the Explorer still lacks repo-specific visual cues for OpenSpec folders, agent surfaces, and hook files.
+- Active Agents rows also do not distinguish Codex/OpenAI versus Claude sessions, snapshot identity, or branch-group semantics in the place operators watch most closely: the working row beside the loader.
+
+## What Changes
+
+- Add a bundled `GitGuardex File Icons` theme to the shipped VS Code companion with distinct icons for OpenSpec `changes`, `plan`, `specs`, agent surfaces, hook paths, and related config/context files.
+- Surface provider-aware Active Agents row copy and badges so Codex/OpenAI sessions read as `OpenAI`, Claude sessions read as `Claude`, snapshot-backed rows show the snapshot name and initial badge, and raw agent branch groups use a branch icon plus `working: agent` state copy.
+- Keep the live extension, template extension, packaging metadata, docs, and focused tests aligned.
+
+## Impact
+
+- Affected surfaces: `vscode/guardex-active-agents/*`, `templates/vscode/guardex-active-agents/*`, `src/context.js`, `test/vscode-active-agents-session-state.test.js`, `test/metadata.test.js`, and `test/setup.test.js`.
+- Risk stays narrow: this is presentation-only work inside the VS Code companion bundle and its packaging metadata.
+- Operator caveat: Explorer icons require selecting the bundled file icon theme inside VS Code; the Active Agents row/provider badges work immediately once the updated extension is installed.
@@ -0,0 +1,55 @@
+## ADDED Requirements
+
+### Requirement: Active Agents rows show provider-aware working state
+
+Active Agents session rows SHALL surface provider identity for Codex/OpenAI and Claude sessions without sacrificing higher-priority warning badges.
+
+#### Scenario: Codex session shows OpenAI branding in the row
+
+- **GIVEN** an active session record whose CLI or agent identity resolves to Codex/OpenAI
+- **WHEN** the Active Agents tree renders the session row
+- **THEN** the row description includes `OpenAI`
+- **AND** the session decoration exposes an `AI` badge whenever no blocked/dead/stalled/idle-threshold badge overrides it
+
+#### Scenario: Snapshot session shows the snapshot name and badge
+
+- **GIVEN** an active session or managed worktree telemetry record carries snapshot identity such as `nagyviktor@edixa.com`
+- **WHEN** the Active Agents tree renders the session row
+- **THEN** the row description includes the snapshot name
+- **AND** the session decoration exposes the first alphanumeric snapshot initial, such as `N`, ahead of provider-only badges
+
+#### Scenario: Claude session shows Claude branding in the row
+
+- **GIVEN** an active session record whose CLI or agent identity resolves to Claude
+- **WHEN** the Active Agents tree renders the session row
+- **THEN** the row description includes `Claude`
+- **AND** the session decoration exposes a `CL` badge whenever no blocked/dead/stalled/idle-threshold badge overrides it
+
+#### Scenario: Raw agent branch groups use branch presentation
+
+- **GIVEN** the Active Agents raw tree groups sessions by worktree branch
+- **WHEN** a worktree group is rendered
+- **THEN** the row uses the VS Code `git-branch` icon instead of the generic folder icon
+- **AND** the row description includes the current state plus agent name, such as `working: codex`
+
+### Requirement: Bundled Explorer file icon theme highlights repo workflow surfaces
+
+The shipped VS Code companion SHALL bundle an optional file icon theme that gives workflow-critical repo paths distinct Explorer icons.
+
+#### Scenario: OpenSpec and workflow folders receive semantic icons
+
+- **GIVEN** the bundled `GitGuardex File Icons` theme is selected in VS Code
+- **WHEN** the Explorer renders folders named `changes`, `plan`, `specs`, `.agents`, `agent-worktrees`, `.githooks`, or `rules`
+- **THEN** each folder uses a bundled semantic icon instead of the generic default
+
+#### Scenario: Key workflow files receive semantic icons
+
+- **GIVEN** the bundled `GitGuardex File Icons` theme is selected in VS Code
+- **WHEN** the Explorer renders workflow files such as `AGENTS.md`, `CLAUDE.md`, `proposal.md`, `tasks.md`, `plan.md`, `spec.md`, `config.yaml`, `.openspec.yaml`, `context-docs-cue.md`, `pre-commit`, `pre-push`, or `post-checkout`
+- **THEN** each file uses the corresponding bundled semantic icon
+
+#### Scenario: Install bundle ships the icon theme assets
+
+- **GIVEN** maintainers install the workspace extension bundle through `scripts/install-vscode-active-agents-extension.js`
+- **WHEN** the extension payload is copied into the VS Code extensions directory
+- **THEN** the installed bundle contains the icon-theme manifest plus the SVG assets referenced by it
@@ -0,0 +1,34 @@
+## Definition of Done
+
+This change is complete only when all of the following are true:
+
+- Every checkbox below is checked.
+- Focused extension/package tests pass.
+- Cleanup records the final PR URL plus `MERGED` evidence, or a `BLOCKED:` line explains why finish could not complete.
+
+Handoff: 2026-04-23 codex owns branch `agent/codex/add-openspec-and-provider-icons-2026-04-23-14-02`, the Active Agents extension bundle, mirrored template files, focused tests, and this OpenSpec change to ship Explorer file icons plus provider-aware Active Agents rows.
+
+## 1. Specification
+
+- [x] 1.1 Finalize proposal scope for Explorer file icons plus provider-aware Active Agents rows.
+- [x] 1.2 Define normative requirements in `specs/vscode-active-agents-provider-icons/spec.md`.
+
+## 2. Implementation
+
+- [x] 2.1 Add bundled file icon theme assets and manifest wiring for OpenSpec, agent, and hook surfaces.
+- [x] 2.2 Add provider/snapshot-aware Active Agents row labels/badges and branch-icon worktree groups without overriding higher-priority warning/idle decorations.
+- [x] 2.3 Keep live/template extension sources, docs, and packaging metadata aligned.
+
+## 3. Verification
+
+- [x] 3.1 Run focused extension/install/package coverage. Result: `node --test test/vscode-active-agents-session-state.test.js test/metadata.test.js test/setup.test.js` passed `102/102`.
+- [x] 3.2 Run `openspec validate agent-codex-add-openspec-and-provider-icons-2026-04-23-14-02 --type change --strict`. Result: passed.
+- [x] 3.3 Run `openspec validate --specs`. Result: `No items found to validate.`
+
+## 4. Cleanup (mandatory; run before claiming completion)
+
+- [ ] 4.1 Run `gx branch finish --branch "agent/codex/add-openspec-and-provider-icons-2026-04-23-14-02" --base main --via-pr --wait-for-merge --cleanup`.
+- [ ] 4.2 Record the PR URL and final `MERGED` state in the completion handoff.
+- [ ] 4.3 Confirm the sandbox worktree and branch refs are gone after cleanup.
+
+BLOCKED:
@@ -129,6 +129,14 @@ const TEMPLATE_FILES = [
   'vscode/guardex-active-agents/session-schema.js',
   'vscode/guardex-active-agents/README.md',
   'vscode/guardex-active-agents/icon.png',
+  'vscode/guardex-active-agents/fileicons/gitguardex-fileicons.json',
+  'vscode/guardex-active-agents/fileicons/icons/agent.svg',
+  'vscode/guardex-active-agents/fileicons/icons/branch.svg',
+  'vscode/guardex-active-agents/fileicons/icons/config.svg',
+  'vscode/guardex-active-agents/fileicons/icons/hook.svg',
+  'vscode/guardex-active-agents/fileicons/icons/openspec.svg',
+  'vscode/guardex-active-agents/fileicons/icons/plan.svg',
+  'vscode/guardex-active-agents/fileicons/icons/spec.svg',
 ];
 
 const PACKAGE_ROOT_SOURCE_OVERRIDES = new Set([
@@ -139,6 +147,14 @@ const PACKAGE_ROOT_SOURCE_OVERRIDES = new Set([
   'vscode/guardex-active-agents/session-schema.js',
   'vscode/guardex-active-agents/README.md',
   'vscode/guardex-active-agents/icon.png',
+  'vscode/guardex-active-agents/fileicons/gitguardex-fileicons.json',
+  'vscode/guardex-active-agents/fileicons/icons/agent.svg',
+  'vscode/guardex-active-agents/fileicons/icons/branch.svg',
+  'vscode/guardex-active-agents/fileicons/icons/config.svg',
+  'vscode/guardex-active-agents/fileicons/icons/hook.svg',
+  'vscode/guardex-active-agents/fileicons/icons/openspec.svg',
+  'vscode/guardex-active-agents/fileicons/icons/plan.svg',
+  'vscode/guardex-active-agents/fileicons/icons/spec.svg',
 ]);
 
 const LEGACY_WORKFLOW_SHIM_SPECS = [

@@ -18,11 +18,14 @@ node scripts/install-vscode-active-agents-extension.js
 What it does:
 
 - Bundles a local GitGuardex icon so repo installs show branded extension metadata inside VS Code.
+- Bundles the optional `GitGuardex File Icons` theme for OpenSpec, agent worktree, and hook files in Explorer.
 - Adds an `Active Agents` view to the Source Control container.
 - Renders one repo node per live Guardex workspace with grouped `ACTIVE AGENTS` and `CHANGES` sections.
 - Splits live sessions inside `ACTIVE AGENTS` into `BLOCKED`, `WORKING NOW`, `THINKING`, `STALLED`, and `DEAD` groups so stuck, active, and inactive lanes stand out immediately.
 - Mirrors the same live state in the VS Code status bar so the selected session or active-agent count stays visible outside the tree.
 - Shows one row per live Guardex sandbox session inside those activity groups, with changed-file rows nested under sessions that are touching files.
+- Labels session rows with provider identity and snapshot context; snapshot-backed rows use a one-letter snapshot badge such as `N` for `nagyviktor@edixa.com`.
+- Shows raw agent branch groups with the `git-branch` icon instead of the generic folder icon.
 - Shows repo-root git changes in a sibling `CHANGES` section when the guarded repo itself is dirty.
 - Derives session state from dirty worktree status, git conflict markers, heartbeat freshness, PID liveness, and recent file mtimes, surfaces working/dead/conflict counts in the repo/header summary, and shows changed-file counts for active edits.
 - Uses distinct VS Code codicons for each session state, including animated `loading~spin` for `WORKING NOW`.