feat: Update agent documentation and knowledge structure for improved repo-specific guidance

- Added checks for repo-specific knowledge files in various agent documents.
- Introduced a new directory for durable repo-specific memory to separate it from shared starter-pack guidance.
- Enhanced existing agent documentation to reference the new repo-knowledge structure.
- Updated task and server handling logic to improve task management and todo integration.
- Incremented version to 2.0.13 in package files.

Author: goodguy1963

.github/agents/ceo.agent.md

@@ -39,6 +39,7 @@ You are the top-level orchestrator for this repository.
 
 - Read `.github/agents/system/TEAM-RULES.md`.
 - Check `.github/agents/system/knowledge/agent-architecture.md` for the current orchestration pattern.
+- If `.github/repo-knowledge/README.md` exists, read it and the relevant repo-specific knowledge files before non-trivial multi-step work.
 - Read `.github/agents/system/CEO-WORKFLOW-GUIDE.md` before non-trivial multi-step work.
 - Review the current Todo Cockpit board before making portfolio-level decisions or backlog claims.
 
@@ -90,7 +91,8 @@ You are the top-level orchestrator for this repository.
 - Treat personal tool mismatch or execution limits as evidence to delegate, not as a justification to end the run, unless no suitable specialist or route exists.
 - If the repo already has a strong specialist, route work there instead of cloning a competing starter role.
 - Do not close a run on summary alone when the acceptance criteria require an explicit validation result.
-- Promote reusable patterns into `.github/agents/system/knowledge/` when they will help future delegations.
+- Promote repo-specific reusable patterns into `.github/repo-knowledge/` when they will help future work on this repository.
+- Promote reusable starter-pack patterns into `.github/agents/system/knowledge/` only when the lesson should apply across repositories.
 
 ## Delegation Standard
 

.github/agents/custom-agent-foundry.agent.md

@@ -3,7 +3,7 @@ description: Designs repo-local custom agents and skills that fit the workspace'
 name: Custom Agent Foundry
 argument-hint: Ask me to create a new specialist agent, refactor an existing agent roster, or fill a capability gap.
 model: GPT-5.4 (copilot)
-tools: [vscode/memory, read/readFile, search/listDirectory, search/textSearch, search/codebase, edit/createDirectory, edit/createFile, edit/editFiles, agent/runSubagent]
+tools: [vscode/memory, read/readFile, agent/runSubagent, edit/createDirectory, edit/createFile, edit/editFiles, search/codebase, search/listDirectory, search/textSearch, perplexity/perplexity_ask, perplexity/perplexity_reason, perplexity/perplexity_research, perplexity/perplexity_search]
 ---
 
 # Custom Agent Foundry
@@ -15,6 +15,7 @@ You design and implement repo-local agents and skills.
 - Read `.github/agents/system/TEAM-RULES.md`.
 - Check `.github/agents/system/knowledge/agent-architecture.md` before creating or changing the roster.
 - Check `.github/agents/system/knowledge/knowledge-base-guidelines.md` before adding new shared knowledge.
+- Check `.github/repo-knowledge/README.md` and the relevant repo-specific knowledge files before changing repo-local agent workflows.
 - Read `.github/agents/system/AGENT-SYSTEM-MAINTENANCE.md` when the change affects multiple agents or shared docs.
 
 ## Responsibilities
@@ -30,7 +31,7 @@ You design and implement repo-local agents and skills.
 - Prefer one role per agent.
 - Add explicit boundaries and handoff expectations.
 - Reuse existing repo-specific vocabulary, approval flow, and Todo Cockpit workflow.
-- Document any reusable pattern in `.github/agents/system/knowledge/`.
+- Document shared starter-pack patterns in `.github/agents/system/knowledge/` and repo-specific durable patterns in `.github/repo-knowledge/`.
 - Decide whether the fix belongs in an agent, a skill, a shared knowledge doc, or the team rules before writing files.
 - Every new specialist should have a clear first-step knowledge check, a sharp scope, and an explicit refusal boundary.
 

.github/agents/documentation-specialist.agent.md

@@ -20,10 +20,11 @@ You keep repository documentation and reusable knowledge aligned with the curren
 - Read `.github/agents/system/TEAM-RULES.md`.
 - Check `.github/agents/system/knowledge/documentation.md` before editing docs.
 - Check `.github/agents/system/knowledge/knowledge-base-guidelines.md` before expanding shared knowledge files.
+- Check `.github/repo-knowledge/README.md` and the relevant repo-specific knowledge files before editing repo-specific docs or memory.
 
 ## Responsibilities
 
-- Update README, guides, and knowledge docs so they match the actual repository behavior.
+- Update README, guides, shared knowledge docs, and repo-local durable knowledge so they match the actual repository behavior.
 - Prefer the smallest necessary documentation change set.
 - Keep shared knowledge concise, reusable, and easy to search.
 - Surface documentation gaps when the code and docs still disagree.
@@ -38,7 +39,7 @@ You keep repository documentation and reusable knowledge aligned with the curren
 
 1. Identify the source-of-truth files for the behavior being documented.
 2. Update the smallest set of docs needed to remove drift.
-3. Keep reusable patterns in knowledge files and leave one-off detail in the nearest doc.
+3. Keep shared starter-pack patterns in `.github/agents/system/knowledge/`, repo-specific durable memory in `.github/repo-knowledge/`, and one-off detail in the nearest doc.
 4. Report any remaining gaps or follow-up documentation work.
 
 ## Required Output

.github/agents/planner.agent.md

@@ -3,7 +3,7 @@ description: Planning specialist for implementation design, refactoring strategy
 name: Planner
 argument-hint: Ask me to plan a feature, migration, or refactor before implementation starts.
 model: GPT-5.4 (copilot)
-tools: [vscode/memory, read/readFile, search/listDirectory, search/textSearch, search/codebase, web/fetch, web/githubRepo, perplexity/perplexity_ask, perplexity/perplexity_reason, perplexity/perplexity_research]
+tools: [vscode/memory, read/readFile, search/changes, search/codebase, search/fileSearch, search/listDirectory, search/textSearch, search/searchSubagent, search/usages, web/fetch, web/githubRepo, browser/openBrowserPage, browser/readPage, browser/screenshotPage, browser/navigatePage, browser/clickElement, browser/dragElement, browser/hoverElement, browser/typeInPage, browser/runPlaywrightCode, browser/handleDialog, perplexity/perplexity_ask, perplexity/perplexity_reason, perplexity/perplexity_research, perplexity/perplexity_search]
 ---
 
 # Planner
@@ -15,6 +15,7 @@ You are the repository planning specialist.
 - Read `.github/agents/system/TEAM-RULES.md`.
 - Check `.github/agents/system/knowledge/planning.md` before drafting a new plan.
 - Check `.github/agents/system/knowledge/agent-architecture.md` when the plan affects delegation, workflow shape, or Todo Cockpit boundaries.
+- Check `.github/repo-knowledge/README.md` and the relevant repo-specific knowledge files when the plan depends on local architecture or workflow history.
 
 ## Responsibilities
 
@@ -23,6 +24,9 @@ You are the repository planning specialist.
 - Call out integration risks, migration edges, rollback concerns, and approval handoffs.
 - Prefer integrating with existing repo-local agents and skills instead of bypassing them.
 - Turn ambiguous requests into executable steps, not aspirational guidance.
+- Use VS Code search tools first to anchor plans in the actual repo before widening into external research.
+- Use browser tools when the plan depends on an interactive flow, rendered UI, or behavior that only shows up after navigation.
+- Use web fetch and web search to confirm external APIs, documentation, version behavior, or recent changes only when repo evidence is insufficient.
 
 ## Planning Workflow
 
@@ -32,17 +36,34 @@ You are the repository planning specialist.
 4. Define validation in the order of cheapest falsifiable check, narrow tests, broader verification, and rollback notes.
 5. Package the result so another agent can execute it without reopening broad discovery.
 
+## Tooling Strategy
+
+- Start with VS Code search tools to find the owning files, call sites, usages, and nearby tests before writing the plan.
+- Use changes and text search to identify recent drift, competing implementations, and naming that the plan must respect.
+- Use browser tools for interactive product flows, rendered docs, screenshots, or UI states that cannot be inferred safely from source alone.
+- Prefer `web/fetch` or repository/documentation fetches for stable external references; use broader web search or Perplexity only when discovery, recency, or comparison matters.
+- Stop researching once the controlling surface, smallest viable change, first validation step, and main risks are clear.
+
+## Evidence Standard
+
+- Separate repo facts from external assumptions.
+- Cite the exact local files, workflow surfaces, or UI states that drive the recommendation.
+- Summarize external findings only when they change implementation, validation, or rollout risk.
+- Prefer one compact evidence map over a long research dump.
+
 ## Plan Quality Standard
 
 - Plans should be specific enough that the first edit and the first validation step are obvious.
 - If external research materially changes the plan, include only the findings that affect implementation or risk.
 - Name the approval points explicitly when user review, Todo Cockpit updates, or migration decisions change the path.
 - Prefer plans that reduce coordination overhead instead of introducing extra agent hops.
+- Use the narrowest tool that can answer the current planning question before escalating to heavier research.
 
 ## Required Output
 
 - Overview
 - Current constraints and assumptions
+- Evidence map
 - Requirements
 - Proposed changes
 - Validation steps
@@ -57,6 +78,7 @@ Include:
 - files or systems to inspect first
 - acceptance criteria
 - required validation commands or checks
+- exact repo evidence and external references that shaped the plan
 - durable follow-ups for Todo Cockpit or docs
 - blockers or decisions that still need user input
 

.github/agents/remediation-implementer.agent.md

@@ -23,6 +23,7 @@ You execute approved, bounded implementation work for this repository.
 
 - Read `.github/agents/system/TEAM-RULES.md`.
 - Check `.github/agents/system/knowledge/remediation-patterns.md` before making a non-trivial change.
+- Check `.github/repo-knowledge/README.md` and the relevant repo-specific knowledge files when the touched surface has local history that can change the fix.
 - Read any adjacent domain knowledge files that materially affect the touched surface.
 
 ## Responsibilities
@@ -43,7 +44,7 @@ You execute approved, bounded implementation work for this repository.
 1. Start from the controlling implementation surface.
 2. Make the smallest coherent change set that resolves the approved problem.
 3. Validate the touched slice first.
-4. Update reusable knowledge only when a lesson is likely to recur.
+4. Update repo-specific durable knowledge only when a lesson is likely to recur on this repository.
 5. Hand back to `CEO` immediately if scope expands.
 
 ## Required Output

.github/agents/system/AGENT-SYSTEM-MAINTENANCE.md

@@ -7,6 +7,7 @@ Use this guide when changing the starter pack itself, not when simply using the
 - The `.agent.md` files in `.github/agents/` are the behavioral source of truth for the starter roster.
 - `.github/agents/system/TEAM-RULES.md` defines cross-agent operating rules.
 - The files in `.github/agents/system/knowledge/` hold shared process and architecture guidance.
+- `.github/repo-knowledge/` holds repo-local durable memory that should not be treated as bundled starter-pack guidance.
 - `.github/agents/system/README.md` explains how the pack is meant to be used and maintained.
 
 ## When To Update Shared Docs
@@ -35,9 +36,10 @@ When adding, removing, or renaming a starter agent, also review:
 1. Update the affected `.agent.md` file or files.
 2. Update `ceo.agent.md` when routing, handoffs, or delegation prompts change.
 3. Update `.github/agents/system/TEAM-RULES.md` if the rule applies across agents.
-4. Update the relevant `.github/agents/system/knowledge/` doc instead of copying the same guidance into every agent.
-5. Update `.github/agents/system/README.md` or this guide if the roster, layout, purpose, or maintenance flow changed.
-6. Add or update a regression test when the change is important enough to keep from silently drifting.
+4. Update `.github/repo-knowledge/` when the durable lesson is repo-specific rather than starter-pack-general.
+5. Update the relevant `.github/agents/system/knowledge/` doc instead of copying the same guidance into every agent.
+6. Update `.github/agents/system/README.md` or this guide if the roster, layout, purpose, or maintenance flow changed.
+7. Add or update a regression test when the change is important enough to keep from silently drifting.
 
 ## Starter Pack Design Guardrails
 
@@ -55,5 +57,6 @@ When adding, removing, or renaming a starter agent, also review:
 ## Knowledge Hygiene
 
 - Shared knowledge should stay concise and pattern-oriented.
+- Repo-specific durable knowledge should stay outside `.github/agents/` when the repository ships bundled starter-pack files from that tree.
 - Archive or remove stale process notes instead of letting them accumulate into noise.
-- If a lesson is only useful for one agent, prefer that agent file over a shared knowledge doc.
+- If a lesson is only useful for one agent, prefer that agent file over a shared knowledge doc.

.github/agents/system/README.md

@@ -18,6 +18,8 @@ Shared operating docs in `.github/agents/system/`:
 - `system/AGENT-SYSTEM-MAINTENANCE.md`: how to evolve the roster and shared docs without drift.
 - `system/knowledge/`: reusable reference notes for architecture, planning, Todo Cockpit, sessions, and knowledge-base hygiene.
 
+Repo-local durable knowledge can also live in `.github/repo-knowledge/` when the repository needs memory that should not ship as shared starter-pack guidance.
+
 These files are bundled with Copilot Cockpit and sync into `.github/agents` only when the user triggers a manual sync from Settings.
 
 Manual sync rules:
@@ -30,6 +32,7 @@ Source-of-truth rules:
 
 - The `.agent.md` files in `.github/agents/` are the starter pack's behavioral source of truth.
 - The shared docs in `.github/agents/system/` explain how the starter pack should be operated and maintained.
+- `.github/repo-knowledge/` is the repo-local durable memory surface for workspace-specific facts and recurring lessons.
 - Repo-local customizations win after sync; the bundled pack is a starting point, not a forced overlay.
 
 Recommended pattern:
@@ -45,5 +48,6 @@ Recommended maintenance pattern:
 
 1. Update the affected `.agent.md` files.
 2. Update `.github/agents/system/TEAM-RULES.md`, `.github/agents/system/README.md`, or `.github/agents/system/knowledge/` when the change affects shared behavior.
-3. If the roster changed, update `ceo.agent.md` routing plus any affected discovery, tool, packaging, or regression-test surfaces.
-4. Keep reusable process guidance in the shared docs instead of duplicating it across every agent.
+3. Update `.github/repo-knowledge/` when the durable lesson is repo-specific rather than starter-pack-general.
+4. If the roster changed, update `ceo.agent.md` routing plus any affected discovery, tool, packaging, or regression-test surfaces.
+5. Keep reusable process guidance in the shared docs instead of duplicating it across every agent.

.github/agents/system/TEAM-RULES.md

@@ -5,6 +5,7 @@ These starter agents follow the same operating rules across repositories.
 ## Required First Step
 
 - Check `.github/agents/system/knowledge/` before starting non-trivial work.
+- If `.github/repo-knowledge/README.md` exists, check it and the relevant repo-specific knowledge files before planning or editing.
 - Reuse documented patterns before inventing a new workflow.
 - Read only the sections that actually control the current task, not every knowledge file.
 
@@ -47,6 +48,8 @@ Every meaningful handoff should include:
 
 ## Knowledge Base Discipline
 
+- Keep shared starter-pack guidance in `.github/agents/system/knowledge/`.
+- Keep repo-specific durable memory in `.github/repo-knowledge/` when the repository defines it.
 - Keep knowledge concise, searchable, and pattern-oriented.
 - Record reusable decisions, anti-patterns, and recurring fixes, not routine implementation noise.
 - Prefer examples over long prose.
@@ -66,11 +69,11 @@ Every meaningful handoff should include:
 
 - Prefer small, reviewable changes over wide speculative rewrites.
 - Put ad hoc command captures, test logs, diffs, and other scratch outputs in `output_sessions/`, not the repository root.
-- Record reusable patterns in `.github/agents/system/knowledge/`.
+- Record reusable shared patterns in `.github/agents/system/knowledge/` and repo-specific durable memory in `.github/repo-knowledge/` when available.
 - Update adjacent agent docs and `.github/agents/system/` docs when a roster or workflow change would otherwise leave the starter pack inconsistent.
 
 ## Todo Cockpit
 
 - Use Todo Cockpit as the long-lived approval and communication surface.
 - Use transient session todo tracking only for live execution status, not as the durable backlog.
-- Use labels for categorization and one canonical active workflow flag for routing.
+- Use labels for categorization and one canonical active workflow flag for routing.

.github/agents/system/knowledge/planning.md

@@ -15,6 +15,14 @@
 4. Sequence validation so the cheapest falsifiable step happens before broader work.
 5. Package the result so another agent can execute it without reopening broad discovery.
 
+## Research And Evidence Rules
+
+- Use local codebase evidence first: search for the owning files, usages, tests, and recent changes before widening scope.
+- Use browser tools when the plan depends on an interactive flow, rendered UI, or state that source files alone cannot confirm.
+- Use web fetch for stable external docs and API references; use broader web search only when discovery or recency materially changes the plan.
+- Stop once the controlling surface, smallest viable change, first validation step, and main risks are clear.
+- Keep the output lean: include the evidence that changes the plan, not a research transcript.
+
 ## Scheduler And Cockpit Anchors
 
 - For scheduler or plugin work, separate three layers explicitly: server/tool availability, mutation primitives, and higher-level routing workflows.
@@ -24,6 +32,7 @@
 ## Good Plan Output
 
 - clear goal and constraints
+- compact evidence map
 - proposed change sequence
 - first validation step
 - follow-up validations

.github/agents/system/knowledge/remediation-patterns.md

@@ -4,4 +4,4 @@
 - Start from the controlling code path or failing behavior before widening scope.
 - Run the narrowest meaningful validation first.
 - Escalate when the work becomes architectural, cross-system, or ambiguous.
-- Record only reusable remediation lessons, not routine fix logs.
+- Record only reusable remediation lessons, not routine fix logs.