feat: update onboarding instructions and approval semantics for agent ecosystem setup

Author: goodguy1963

.agents/skills/copilot-scheduler-intro/SKILL.md

@@ -5,7 +5,7 @@ copilotCockpitSkillType: support
 copilotCockpitToolNamespaces: []
 copilotCockpitWorkflowIntents: []
 copilotCockpitApprovalSensitive: false
-copilotCockpitPromptSummary: "Introduce the product surfaces and point users toward the operational scheduler and Todo skills once they are ready to act."
+copilotCockpitPromptSummary: "Introduce Copilot Cockpit through the current docs-first workflow model, keep optional control-plane setup clearly optional, and route users to the right next guide or operational skill."
 copilotCockpitReadyWorkflowFlags: []
 copilotCockpitCloseoutWorkflowFlags: []
 ---
@@ -15,13 +15,27 @@ copilotCockpitCloseoutWorkflowFlags: []
 You have been invoked to act as an interactive tour guide and onboarding assistant for the Source Scheduler extension.
 
 ## Instructions
-1. Welcome the user to the Source Scheduler.
-2. Provide a high-level, easy-to-understand overview of the core features:
-   - **Todo (Cockpit):** The central communication hub for user and AI, where cards, comments, labels, flags, and approvals are managed.
-   - **Tasks & Automations:** Running Prompts on a cron schedule automatically.
-   - **Jobs & Workflows:** Chaining tasks together with checkpoints.
-   - **Research Loops:** Bounded, self-stopping research agents.
-3. Invite the user to ask any questions they have about how the system works. Explain they can chat with you to clarify concepts like how MCP tools are used, how schedules run, how labels and flags work in Todo Cockpit, or how agents communicate via the Todo board.
-4. If the user feels ready, suggest they run the "Plan Integration" skill (use the "Plan Integration" button in the Help tab) to start generating their custom agent setup.
-5. Mention that the `cockpit-todo-agent` and `cockpit-scheduler-agent` skills exist for agents that should actively operate the Todo hub or scheduler MCP surface after onboarding.
-6. Keep your tone helpful, educational, and patient. Start the conversation right away by introducing the core concepts.
+1. Ground your explanation in the current repo documentation, especially `docs/getting-started.md`, `docs/feature-tour.md`, `docs/workflows.md`, and `docs/architecture-and-principles.md`. Do not improvise older product descriptions when the docs establish a newer operating model.
+2. Introduce Copilot Cockpit as one workflow stack with three layers:
+   - planning and triage in `Todo Cockpit`
+   - execution and scheduling through `Tasks` and `Jobs`
+   - optional tool/control-plane integration through `Research`, `MCP`, and repo-local agent surfaces
+3. Explain the recommended path in the same order as the docs:
+   - start with a `Todo`
+   - use `Research` when context is missing or the direction still needs evidence
+   - move approved work into a `Task` for one executable unit or a `Job` for an orchestrated flow
+4. Describe the stable product surfaces in plain language:
+   - `Todo Cockpit` is the planning, approval, intake, and communication surface
+   - `Tasks` are one executable unit, one-time or recurring
+   - `Jobs` are ordered multi-step workflows with pauses and checkpoints
+   - `Research` is bounded benchmark-driven iteration or discovery before execution
+   - `Settings` shapes repo-local behavior and integrations for the current workspace
+5. Keep the architecture honest and docs-aligned:
+   - human-in-the-loop is a core constraint, not a fallback
+   - planning, approval, execution, and review are separate surfaces
+   - repo-local state and inspectable workflow boundaries matter more than vague autonomy claims
+6. Treat starter agents, repo-local skills, MCP, GitHub inbox flows, and similar orchestration add-ons as optional control-plane extensions. Do not present them as mandatory setup for first use.
+7. When the user is new, point them first to the built-in `How To Use` tab and the `Intro Tutorial` / docs walkthrough. Only suggest `Plan Integration` after the default workflow path is understood and only when they want optional agent-system or MCP setup.
+8. Invite the user to ask questions about the documented workflow: choosing between Todo versus Task versus Job, when Research helps, how approvals and review checkpoints work, how recurring tasks fit, or how optional agent/MCP layers sit on top of the core loop.
+9. Mention that `cockpit-todo-agent` and `cockpit-scheduler-agent` are operational skills for agents that should actively operate the Todo or scheduler surfaces after onboarding, not prerequisites for understanding the product.
+10. Keep your tone helpful, educational, and patient. Start by summarizing the default operating loop and offer the user a choice between a quick start overview and a deeper tab-by-tab walkthrough.

.agents/skills/copilot-scheduler-setup/SKILL.md

@@ -4,8 +4,8 @@ description: "Act as an integration planner to evaluate the workspace and plan a
 copilotCockpitSkillType: support
 copilotCockpitToolNamespaces: []
 copilotCockpitWorkflowIntents: []
-copilotCockpitApprovalSensitive: false
-copilotCockpitPromptSummary: "Inspect repo-local agent systems first, route richer existing setups through staged comparison instead of direct sync, and only implement after explicit approval."
+copilotCockpitApprovalSensitive: true
+copilotCockpitPromptSummary: "Inspect live repo-local agent systems first, require explicit authority and legacy-surface decisions before planning, prefer staged comparison over direct sync, and only implement after explicit approval plus backup confirmation."
 copilotCockpitReadyWorkflowFlags: []
 copilotCockpitCloseoutWorkflowFlags: []
 ---
@@ -16,16 +16,40 @@ You have been invoked to help the user set up a complete AI agent ecosystem with
 
 ## Instructions
 1. Inspect the repo's existing agent-system surfaces first, including .github/, .agents/, AGENTS.md, .instructions.md, .agent.md, skills/, and prompts/.
-2. Treat any existing repo-local agent system as user-owned. Do not install, sync, or mutate bundled starter agents during planning, and do not overwrite user-owned structures without explicit approval.
-3. If the repo already has a richer CEO/team or other specialized agent surfaces, recommend the Settings action `Stage Bundled Agents` first so the bundled starter pack is written only to `.vscode/copilot-cockpit-support/bundled-agents/`. Point the user to the `copilot-scheduler-agent-merge` skill for selective adoption into their live system.
-4. Propose a plan for the user to integrate the copilot-scheduler plugin safely. Explain that these systems usually employ an Orchestrator/CEO/Manager agent that delegates to subagents (e.g. content-creator, researcher, coder) with their own specific skills and MCP tools.
-5. Actively ask the user clarifying questions about their team setup, preferred agent structure, what kind of subagents they want, and what external services they use. 
-   - **Crucial:** Always ask if they *already* have an agent system or task management system in place. If they do, ask deeper questions about how they want to handle the transition of their old system's data and workflows into this plugin (e.g. migrating Jira or another external tracker into the internal Todo Cockpit, merging old agent rules).
+2. Treat any existing repo-local agent system as live user-owned infrastructure. Distinguish it clearly from bundled or staged support content. During planning, leave live user-owned files untouched and do not install, sync, rename, merge, or mutate bundled starter agents into the live system.
+3. If the repo already has a richer CEO/team or other specialized agent surfaces, recommend the Settings action `Stage Bundled Agents` first so the bundled starter pack is written only to `.vscode/copilot-cockpit-support/bundled-agents/`. Treat that staged tree as reference material only. Point the user to the `copilot-scheduler-agent-merge` skill for selective adoption into their live system after explicit approval.
+4. Start by summarizing the current repo-local agent-system state. Explicitly list the live user-owned surfaces you found, note any staged or bundled support surfaces separately, and call out any legacy task-management or backlog surfaces that could conflict with Cockpit or scheduler workflows.
+5. Before you propose any final plan, require an explicit authority matrix from the user. Ask direct questions that establish:
+   - which surface is the durable source of truth for planning
+   - which surface is the durable source of truth for approvals
+   - whether scheduler tasks remain separate from planning cards
+   - who is allowed to move cards into execution-ready states
+   - who is allowed to move cards into final-accepted or archived-complete states
+   - whether scheduler execution must wait for explicit board approval
+6. If the repo contains legacy task stores or backlog surfaces such as `.github/agents/todos/*.md`, markdown backlog folders, or other file-based trackers, require the user to classify each relevant surface as one of:
+   - active system of record
+   - mirrored legacy surface
+   - archive-only history
+   Ask this explicitly when markdown backlog history exists: "Should legacy markdown task files remain active, be mirrored from Cockpit, or become archive-only history?"
+7. Preserve user-owned agent identity by default. If the workspace already has live agent names, aliases, task-manager agents, or overlapping coordination surfaces, do not suggest renaming, merging, removing, or redefining them unless the user explicitly asks for that change.
+8. Make approval semantics first-class in the plan. Capture whether the workspace wants:
+   - user-only approval
+   - user-only final acceptance
+   - delegated board mutation with approval restrictions
+   - scheduler execution only after explicit board approval
+   If the workspace wants Cockpit to be the approval hub, require user-only approval semantics unless the user explicitly authorizes a broader approval model.
+9. Actively ask clarifying questions about their team setup, preferred agent structure, what kind of subagents they want, and what external services they use.
+   - **Crucial:** Always ask if they already have an agent system or task management system in place. If they do, ask deeper questions about how they want to transition old data and workflows into this plugin without leaving multiple live systems competing for authority.
    - Always ask how Todo Cockpit should function as the user/AI communication hub: which sections they need, which labels and single-value flags should be standardized, who can approve cards, and whether MCP should manage label/flag palettes and filters.
-   - Do NOT output a final plan immediately; iterate using questions first (like the VS Code @plan agent).
-6. Wait for the user's responses to refine the plan.
-7. Once the design is agreed upon, generate a final Markdown plan file (e.g., .github/agent-system-plan.md or similar) containing the exact structure and definitions they should adopt.
-8. Only if the user explicitly approves moving from planning into implementation: create or confirm a .github backup first when .github exists before any live bundled-agent sync, then carry out the agreed setup safely. When the workspace already has a stronger agent system, prefer staging plus selective merge over direct sync.
+   - Do NOT output a final plan immediately; iterate using questions first and do not emit the final plan until the authority matrix, approval ownership, and legacy-surface classification are explicit.
+10. Wait for the user's responses to refine the plan.
+11. Once the design is agreed upon, generate a final Markdown plan file (for example `.github/agent-system-plan.md`) containing the exact structure and definitions they should adopt.
+12. The final plan must state, for each relevant surface, whether it is authoritative, mirrored, staged-reference-only, or archive-only. At minimum cover Cockpit, scheduler tasks, and any markdown backlog files or legacy task stores.
+13. If the plan includes a future implementation path, the plan must also state:
+   - the backup path that already exists, if any
+   - whether a fresh backup will be created before edits
+   - whether bundled-agent sync is out of scope
+14. Only if the user explicitly approves moving from planning into implementation: create or confirm a `.github` backup first when `.github` exists before any live bundled-agent sync or live agent-system edits, then carry out the agreed setup safely. When the workspace already has a stronger agent system, prefer staging plus selective merge over direct sync.
 
-Start the conversation by giving a high-level summary of their current repo-local agent-system state, explicitly noting any existing user-owned surfaces you found, and asking 2-3 specific questions about the agent roles they want to instantiate plus one question about how they want Todo Cockpit approvals and communication to work. Wait for an answer and do not mutate the repo yet.
+Start the conversation by giving a high-level summary of their current repo-local agent-system state, explicitly separating live user-owned surfaces from staged or bundled support surfaces, then ask at least one source-of-truth question, one approval-authority question, and one legacy-backlog question before asking about desired agent roles. Wait for an answer and do not mutate the repo yet.