recodeee · NagyVikt · Apr 22, 2026 · Apr 22, 2026
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-22
@@ -0,0 +1,17 @@
+## Why
+
+- The VS Code extension details page for `GitGuardex Active Agents` still shows the default placeholder icon even though the repo already ships a root `logo.png`.
+- The current Active Agents implementation already covers more of the user's requested runtime behavior than the brief assumes, so execution needs a delta-only plan instead of a rewrite.
+- We need one scoped follow-up change that ties branding, install packaging, duplicated extension sources, runtime polish audit, docs, tests, and finish-flow verification together.
+
+## What Changes
+
+- Add a branded extension-icon lane that packages a copy of the repo `logo.png` inside the installable extension payload and wires the manifest to it.
+- Audit the shipped Active Agents companion against the requested runtime brief and only implement still-missing deltas after that audit.
+- Keep `vscode/guardex-active-agents/*`, `templates/vscode/guardex-active-agents/*`, install behavior, README guidance, and focused regression coverage aligned.
+
+## Impact
+
+- Affected surfaces: `logo.png`, `vscode/guardex-active-agents/*`, `templates/vscode/guardex-active-agents/*`, `scripts/install-vscode-active-agents-extension.js`, `test/vscode-active-agents-session-state.test.js`, and README surfaces that describe local install/use.
+- Primary risk is duplicate work: grouped state sections, repo `CHANGES`, lock-aware decorations, and `AGENT.lock` fallback already exist, so the implementation lane must prove any runtime gap before editing provider logic.
+- Packaging risk is narrow but real: the extension icon must resolve from inside the installed extension directory, not from the repo root.
@@ -0,0 +1,28 @@
+## ADDED Requirements
+
+### Requirement: Active Agents ships a branded extension icon
+The GitGuardex Active Agents extension SHALL package a branded icon that resolves from inside the installed extension directory.
+
+#### Scenario: Local install includes packaged icon asset
+- **WHEN** `scripts/install-vscode-active-agents-extension.js` installs the extension
+- **THEN** the installed extension directory contains an icon asset derived from the repo `logo.png`
+- **AND** `vscode/guardex-active-agents/package.json` points its `icon` field at that packaged asset
+- **AND** VS Code can show the branded icon instead of the default placeholder on the extension details page.
+
+### Requirement: Mirrored extension sources stay consistent
+User-visible Active Agents extension behavior SHALL stay aligned across the duplicated `vscode/guardex-active-agents/` and `templates/vscode/guardex-active-agents/` trees unless the change intentionally collapses them to one canonical source.
+
+#### Scenario: Branding or runtime changes touch duplicated extension files
+- **WHEN** this change updates extension packaging, manifest metadata, runtime behavior, or bundled assets
+- **THEN** the same shipped behavior is present in both source trees
+- **OR** the change removes one source tree and updates installer/tests to the new single source of truth in the same change
+- **AND** focused regression coverage validates the shipped install payload.
+
+### Requirement: Runtime follow-up stays delta-based
+This follow-up SHALL preserve the already-shipped Active Agents grouped tree behavior and only add runtime changes that are still missing after audit.
+
+#### Scenario: Runtime brief overlaps already-landed features
+- **WHEN** the executor compares the requested runtime brief against the current extension code and prior Active Agents change specs
+- **THEN** grouped `ACTIVE AGENTS` and repo `CHANGES` behavior, group ordering, lock awareness, and `AGENT.lock` fallback remain intact
+- **AND** only unsatisfied deltas are added to `extension.js`, `session-schema.js`, related docs, or tests
+- **AND** the change does not reimplement already-shipped behavior solely because it appeared in the user brief.
@@ -0,0 +1,41 @@
+## Definition of Done
+
+This change is complete only when **all** of the following are true:
+
+- Every checkbox below is checked.
+- The agent branch reaches `MERGED` state on `origin` and the PR URL + state are recorded in the completion handoff.
+- If any step blocks (test failure, conflict, ambiguous result), append a `BLOCKED:` line under section 5 explaining the blocker and **STOP**. Do not tick remaining cleanup boxes; do not silently skip the cleanup pipeline.
+
+## Handoff
+
+- Handoff: change=`agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05`; branch=`agent/codex/vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05`; scope=`logo.png packaging for the Active Agents extension, delta-only runtime audit, mirrored source parity, focused tests/docs`; action=`continue in this sandbox, execute the phase board in openspec/plan/agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05/, and finish with gx branch finish after validation`.
+- Copy prompt: Continue `agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05` on branch `agent/codex/vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05`. Work inside the existing sandbox, review `openspec/changes/agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05/tasks.md`, continue from the current state instead of creating a new sandbox, and when the work is done run `gx branch finish --branch agent/codex/vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05 --base main --via-pr --wait-for-merge --cleanup`.
+
+## 1. Specification
+
+- [x] 1.1 Finalize proposal scope around extension branding, install payload behavior, mirrored extension-source parity, and delta-only runtime follow-up.
+- [x] 1.2 Define normative requirements in `specs/vscode-active-agents-extension/spec.md`.
+
+## 2. Planning
+
+- [x] 2.1 Create an execution-ready plan workspace under `openspec/plan/agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05/`.
+- [x] 2.2 Replace generic role task scaffolds with concrete lanes for planner, architect, critic, executor, writer, and verifier.
+- [ ] 2.3 Fold any later architect/critic review back into the plan before code edits start.
+
+## 3. Implementation
+
+- [ ] 3.1 Package a branded extension icon using the existing repo `logo.png` and wire it into the installed extension manifest.
+- [ ] 3.2 Audit the current Active Agents code/specs against the requested runtime brief and only land still-missing deltas.
+- [ ] 3.3 Keep `vscode/guardex-active-agents/*`, `templates/vscode/guardex-active-agents/*`, docs, and focused tests aligned.
+
+## 4. Verification
+
+- [ ] 4.1 Run focused extension/install coverage, including `node --test test/vscode-active-agents-session-state.test.js`.
+- [ ] 4.2 Run `openspec validate agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05 --type change --strict`.
+- [ ] 4.3 Run `openspec validate --specs`.
+
+## 5. Cleanup (mandatory; run before claiming completion)
+
+- [ ] 5.1 Run the cleanup pipeline: `gx branch finish --branch agent/codex/vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05 --base main --via-pr --wait-for-merge --cleanup`. This handles commit -> push -> PR create -> merge wait -> worktree prune in one invocation.
+- [ ] 5.2 Record the PR URL and final merge state (`MERGED`) in the completion handoff.
+- [ ] 5.3 Confirm the sandbox worktree is gone (`git worktree list` no longer shows the agent path; `git branch -a` shows no surviving local/remote refs for the branch).
@@ -0,0 +1,19 @@
+# Plan Workspace: agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05
+
+This folder stores durable planning artifacts before implementation changes.
+
+## Role folders
+- `planner/`
+- `architect/`
+- `critic/`
+- `executor/`
+- `writer/`
+- `verifier/`
+
+Each role folder contains OpenSpec-style artifacts:
+- `.openspec.yaml`
+- `proposal.md`
+- `tasks.md` (Spec / Tests / Implementation / Checkpoints checklists)
+- `specs/<role>/spec.md`
+Planner also gets `plan.md`; executor also gets `checkpoints.md`.
+Planner plans should follow `openspec/plan/PLANS.md`.
@@ -0,0 +1,8 @@
+schema: 1
+plan: agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05
+role: architect
+status: draft
+artifacts:
+  proposal: proposal.md
+  tasks: tasks.md
+  spec: specs/architect/spec.md
@@ -0,0 +1,11 @@
+# architect
+
+Role workspace for `architect`.
+
+Default artifacts:
+- `.openspec.yaml`
+- `proposal.md`
+- `tasks.md`
+- `specs/<role>/spec.md`
+
+Use this folder for role notes, artifacts, and status updates.
@@ -0,0 +1,15 @@
+# Proposal: architect (agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05)
+
+## Why
+
+Summarize why this role's work is required for plan `agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05`.
+
+## What Changes
+
+- [ ] List the planned role-specific changes
+
+## Impact
+
+- Scope:
+- Risks:
+- Dependencies:
@@ -0,0 +1,10 @@
+# Capability Spec: architect
+
+## ADDED Requirements
+
+### Requirement: architect responsibilities for `agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05`
+This role MUST define and deliver its scoped outputs with evidence.
+
+#### Scenario: Role executes assigned scope
+- **WHEN** the role begins execution for `agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05`
+- **THEN** it follows `tasks.md` and records evidence for completion
@@ -0,0 +1,32 @@
+# architect tasks
+
+## 1. Spec
+
+- [ ] 1.1 Decide whether this lane keeps `vscode/guardex-active-agents/` and `templates/vscode/guardex-active-agents/` mirrored or intentionally collapses them to one canonical source.
+- [ ] 1.2 Lock the packaged-icon strategy: committed asset copy inside the extension tree versus any generated/install-time alternative.
+
+## 2. Tests
+
+- [ ] 2.1 Define compatibility checks for VS Code manifest `icon` metadata, installer payload copying, and mirrored-source parity.
+- [ ] 2.2 Validate that any runtime follow-up preserves grouped `ACTIVE AGENTS` / `CHANGES`, lock-aware rows, and `AGENT.lock` fallback behavior.
+
+## 3. Implementation
+
+- [ ] 3.1 Compare the viable options: in-place patch, source-tree canonicalization, or installer-time asset injection.
+- [ ] 3.2 Record the chosen architecture and guardrails in `planner/plan.md`.
+- [ ] 3.3 Publish architecture sign-off notes for downstream execution.
+
+## 4. Checkpoints
+
+- [ ] [A1] READY - Architecture review checkpoint
+
+## 5. Collaboration
+
+- [ ] 5.1 Owner recorded this lane before edits.
+- [ ] 5.2 Record joined agents / handoffs, or mark `N/A` when solo.
+
+## 6. Cleanup
+
+- [ ] 6.1 If this lane owns finalization, run `gx branch finish --branch agent/codex/vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05 --base main --via-pr --wait-for-merge --cleanup`.
+- [ ] 6.2 Record PR URL + final `MERGED` state in the handoff.
+- [ ] 6.3 Confirm sandbox cleanup (`git worktree list`, `git branch -a`) or append `BLOCKED:` and stop.
@@ -0,0 +1,4 @@
+# Plan Checkpoints: agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05
+
+Chronological checkpoint log for all roles.
+
@@ -0,0 +1,37 @@
+# Master Coordinator Prompt
+
+You are the coordinator for plan `agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05`.
+
+## Objective
+
+Drive this plan from draft to execution-ready status with strict checkpoint discipline and no scope drift.
+
+## Source-of-truth artifacts
+
+- `openspec/plan/agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05/summary.md`
+- `openspec/plan/agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05/checkpoints.md`
+- `openspec/plan/agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05/planner/plan.md`
+- role `tasks.md` files for planner/architect/critic/executor/writer/verifier
+
+## Coordinator responsibilities
+
+1. Keep checkpoints current in each role `tasks.md` and root `checkpoints.md`.
+2. Ensure each role has explicit acceptance criteria and verification evidence.
+3. Prevent implementation from starting before planning gates are complete.
+4. Keep handoffs concise: files changed, behavior touched, verification output, risks.
+
+## Wave-splitting decision (optional)
+
+Create wave prompts in `kickoff-prompts.md` only when at least one applies:
+
+- 3+ independent implementation lanes can run in parallel.
+- Runtime cutover/rollback sequencing needs explicit lane ownership.
+- Risk is high enough that bounded execution packets reduce coordination mistakes.
+
+If wave splitting is not needed, keep execution under a single owner with normal role checkpoints.
+
+## Exit criteria
+
+- All role checkpoints required for planning are done.
+- Execution lanes (if any) have clear ownership boundaries.
+- Verification plan and rollback expectations are explicit and testable.
@@ -0,0 +1,8 @@
+schema: 1
+plan: agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05
+role: critic
+status: draft
+artifacts:
+  proposal: proposal.md
+  tasks: tasks.md
+  spec: specs/critic/spec.md
@@ -0,0 +1,11 @@
+# critic
+
+Role workspace for `critic`.
+
+Default artifacts:
+- `.openspec.yaml`
+- `proposal.md`
+- `tasks.md`
+- `specs/<role>/spec.md`
+
+Use this folder for role notes, artifacts, and status updates.
@@ -0,0 +1,15 @@
+# Proposal: critic (agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05)
+
+## Why
+
+Summarize why this role's work is required for plan `agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05`.
+
+## What Changes
+
+- [ ] List the planned role-specific changes
+
+## Impact
+
+- Scope:
+- Risks:
+- Dependencies:
@@ -0,0 +1,10 @@
+# Capability Spec: critic
+
+## ADDED Requirements
+
+### Requirement: critic responsibilities for `agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05`
+This role MUST define and deliver its scoped outputs with evidence.
+
+#### Scenario: Role executes assigned scope
+- **WHEN** the role begins execution for `agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05`
+- **THEN** it follows `tasks.md` and records evidence for completion
@@ -0,0 +1,32 @@
+# critic tasks
+
+## 1. Spec
+
+- [ ] 1.1 Validate that the plan stays delta-based and does not reopen already-landed Active Agents features without evidence.
+- [ ] 1.2 Validate that risks, consequences, and mitigations are explicit for asset packaging, mirrored sources, and finish-flow cleanup.
+
+## 2. Tests
+
+- [ ] 2.1 Validate that every acceptance criterion maps to a concrete proof surface: installed asset, focused tests, OpenSpec validation, or merge evidence.
+- [ ] 2.2 Validate that the verification steps are concrete and reproducible from the sandbox worktree.
+
+## 3. Implementation
+
+- [ ] 3.1 Produce a verdict (`APPROVE`, `ITERATE`, or `REJECT`) on the plan and call out any unnecessary runtime work.
+- [ ] 3.2 Confirm revised drafts resolve prior findings before approval.
+- [ ] 3.3 Publish final quality/risk sign-off notes.
+
+## 4. Checkpoints
+
+- [ ] [C1] READY - Quality gate checkpoint
+
+## 5. Collaboration
+
+- [ ] 5.1 Owner recorded this lane before edits.
+- [ ] 5.2 Record joined agents / handoffs, or mark `N/A` when solo.
+
+## 6. Cleanup
+
+- [ ] 6.1 If this lane owns finalization, run `gx branch finish --branch agent/codex/vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05 --base main --via-pr --wait-for-merge --cleanup`.
+- [ ] 6.2 Record PR URL + final `MERGED` state in the handoff.
+- [ ] 6.3 Confirm sandbox cleanup (`git worktree list`, `git branch -a`) or append `BLOCKED:` and stop.
@@ -0,0 +1,8 @@
+schema: 1
+plan: agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05
+role: executor
+status: draft
+artifacts:
+  proposal: proposal.md
+  tasks: tasks.md
+  spec: specs/executor/spec.md
@@ -0,0 +1,11 @@
+# executor
+
+Role workspace for `executor`.
+
+Default artifacts:
+- `.openspec.yaml`
+- `proposal.md`
+- `tasks.md`
+- `specs/<role>/spec.md`
+
+Use this folder for role notes, artifacts, and status updates.
@@ -0,0 +1,4 @@
+# executor checkpoints
+
+Timestamped execution checkpoints for `agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05`.
+
@@ -0,0 +1,15 @@
+# Proposal: executor (agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05)
+
+## Why
+
+Summarize why this role's work is required for plan `agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05`.
+
+## What Changes
+
+- [ ] List the planned role-specific changes
+
+## Impact
+
+- Scope:
+- Risks:
+- Dependencies:
@@ -0,0 +1,10 @@
+# Capability Spec: executor
+
+## ADDED Requirements
+
+### Requirement: executor responsibilities for `agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05`
+This role MUST define and deliver its scoped outputs with evidence.
+
+#### Scenario: Role executes assigned scope
+- **WHEN** the role begins execution for `agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05`
+- **THEN** it follows `tasks.md` and records evidence for completion
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,4 @@
		# Plan Checkpoints: agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05

		Chronological checkpoint log for all roles.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,4 @@
		# executor checkpoints

		Timestamped execution checkpoints for `agent-codex-vscode-active-agents-logo-and-runtime-pl-2026-04-22-16-05`.