From f56b4912a08773b3315594ebaa46012a3804c081 Mon Sep 17 00:00:00 2001 From: Adam Polak Date: Sun, 15 Mar 2026 13:06:50 +0100 Subject: [PATCH 1/4] feat: support for multiple knowledge and task agents --- .github/agents/tsh-architect.agent.md | 22 +- .github/agents/tsh-business-analyst.agent.md | 69 ++-- .github/agents/tsh-code-reviewer.agent.md | 17 +- .github/agents/tsh-context-engineer.agent.md | 35 +- .github/agents/tsh-e2e-engineer.agent.md | 4 +- .../agents/tsh-engineering-manager.agent.md | 19 +- .github/agents/tsh-knowledge.agent.md | 77 +++++ .github/internal-prompts/tsh-plan.prompt.md | 4 +- .../internal-prompts/tsh-research.prompt.md | 6 +- .../prompts/tsh-analyze-materials.prompt.md | 25 +- .../skills/tsh-jira-task-formatting/SKILL.md | 22 +- .../jira-task.example.md | 2 +- .../tsh-shortcut-task-formatting/SKILL.md | 231 +++++++++++++ .../shortcut-task.example.md | 309 ++++++++++++++++++ .github/skills/tsh-task-analysing/SKILL.md | 3 +- .github/skills/tsh-task-extracting/SKILL.md | 4 +- .../tsh-task-quality-reviewing/SKILL.md | 23 +- .github/skills/tsh-using-atlassian/SKILL.md | 103 ++++++ .github/skills/tsh-using-shortcut/SKILL.md | 136 ++++++++ .vscode/mcp.json | 10 + README.md | 94 ++++-- website/docs/agents/overview.md | 29 -- website/docs/getting-started/quick-wins.md | 37 ++- website/docs/intro.md | 12 +- website/docs/prompts/overview.md | 18 +- website/docs/workflow/frontend-flow.md | 14 +- website/docs/workflow/overview.md | 34 +- 27 files changed, 1129 insertions(+), 230 deletions(-) create mode 100644 .github/agents/tsh-knowledge.agent.md create mode 100644 .github/skills/tsh-shortcut-task-formatting/SKILL.md create mode 100644 .github/skills/tsh-shortcut-task-formatting/shortcut-task.example.md create mode 100644 .github/skills/tsh-using-atlassian/SKILL.md create mode 100644 .github/skills/tsh-using-shortcut/SKILL.md diff --git a/.github/agents/tsh-architect.agent.md b/.github/agents/tsh-architect.agent.md index ccdd2903..daf6abe9 100644 --- a/.github/agents/tsh-architect.agent.md +++ b/.github/agents/tsh-architect.agent.md @@ -3,7 +3,6 @@ description: "Agent specializing in designing the solution architecture and tech tools: [ "execute", - "atlassian/*", "context7/*", "figma-mcp-server/*", "pdf-reader/*", @@ -76,16 +75,17 @@ Before finalizing the technical specifications, ensure to review them thoroughly - `tsh-implementing-observability` - when designing monitoring architecture, SLO frameworks, alerting strategies, or distributed tracing. - `tsh-engineering-prompts` - when designing LLM prompt architecture: prompt template strategy, system prompt design, few-shot vs zero-shot decisions, prompt versioning approach. -## Tool Usage Guidelines +## Agents Delegation Guidelines -You have access to the `Atlassian` tool. +You have access to the `tsh-knowledge` agent. +- **MUST delegate to when**: + - Accessing structured knowledge from external systems like Jira, Shortcut, and Confluence to gather requirements, technical context, project conventions, and implementation guidelines for the project. This includes: + - Accessing task details from task management systems like Jira or Shortcut to gather requirements and context for implementation tasks. + - Accessing documentation from knowledge bases like Confluence to gather technical context, project conventions, and implementation guidelines for the project. +- **IMPORTANT**: + - When asked about anything related to tasks or knowledge, always run the `tsh-knowledge` subagent first as this is the only agent with access to structured external knowledge. This ensures that your responses are informed by the most accurate and up-to-date information from the project management and documentation systems. -- **MUST use when**: - - Provided with Jira issue keys or Confluence page IDs to gather relevant information. - - Extending your understanding of technical requirements documented in Jira or Confluence. -- **SHOULD NOT use for**: - - Non-Atlassian related research or documentation. - - Lack of IDs or keys to reference specific Jira issues or Confluence pages. +## Tool Usage Guidelines You have access to the `context7` tool. @@ -121,7 +121,7 @@ You have access to the `pdf-reader` tool. - **MUST use when**: - Task references or links to PDF documents containing technical specifications, API documentation, architecture diagrams, or compliance requirements. - A user attaches, mentions, or references a PDF file relevant to the architectural design. - - Reviewing PDF materials linked in Jira, Confluence, research files, or provided directly by the user. + - Reviewing PDF materials linked in Jira, Shortcut, Confluence, research files, or provided directly by the user. - **IMPORTANT**: - Use this tool to read the full content of PDF files before incorporating them into the architectural design. - Extract technical constraints, integration requirements, data models, API contracts, and non-functional requirements from PDF content. @@ -168,7 +168,7 @@ You have access to the `vscode/askQuestions` tool. - Validating assumptions about constraints or non-functional requirements. - **IMPORTANT**: - Keep questions focused and specific. Batch related questions together rather than asking one at a time. - - Prefer resolving unknowns from the codebase, Jira, or Confluence first — only ask the user when other sources are insufficient. + - Prefer resolving unknowns from the codebase, task management tools, or Confluence first — only ask the user when other sources are insufficient. - **SHOULD NOT use for**: - Questions answerable from the codebase or available documentation. - Implementation details that are the software engineer's responsibility. diff --git a/.github/agents/tsh-business-analyst.agent.md b/.github/agents/tsh-business-analyst.agent.md index 68a2b6db..427ecf89 100644 --- a/.github/agents/tsh-business-analyst.agent.md +++ b/.github/agents/tsh-business-analyst.agent.md @@ -1,6 +1,6 @@ --- -description: "Agent specializing in converting discovery workshop materials (transcripts, designs, codebase context) into Jira-ready epics and user stories." -tools: ['atlassian/*', 'figma-mcp-server/*', 'pdf-reader/*', 'sequential-thinking/*', 'read', 'edit', 'search', 'todo', 'agent', 'vscode/askQuestions'] +description: "Agent specializing in converting discovery workshop materials (transcripts, designs, codebase context) into structured epics and user stories for task management tools." +tools: ['figma-mcp-server/*', 'pdf-reader/*', 'sequential-thinking/*', 'read', 'edit', 'search', 'todo', 'agent', 'vscode/askQuestions'] handoffs: - label: Start Implementation agent: tsh-engineering-manager @@ -10,11 +10,11 @@ handoffs: ## Agent Role and Responsibilities -Role: You are a business analyst that specializes in converting discovery workshop materials into structured, Jira-ready epics and user stories. You process raw inputs (call transcripts, Figma designs, existing codebase context, and other reference materials), extract actionable work items, and format them for direct creation in Jira. +Role: You are a business analyst that specializes in converting discovery workshop materials into structured epics and user stories ready for task management tools (Jira or Shortcut). You process raw inputs (call transcripts, Figma designs, existing codebase context, and other reference materials), extract actionable work items, and format them for direct creation in the target task management tool. -You also support a **Jira iteration mode**: when the user wants to work with existing Jira tasks (rather than workshop materials), you can import issues from Jira into the local `jira-tasks.md` format, iterate on them locally, and push changes back to Jira on demand. +You also support an **iteration mode**: when the user wants to work with existing tasks (rather than workshop materials), you can import issues from the task management tool into the local `formatted-tasks.md` format, iterate on them locally, and push changes back on demand. -You are a thin orchestrator — your primary job is to coordinate the skills that do the heavy lifting, manage user interactions and review gates, and handle the final Jira push via Atlassian tools. +You are a thin orchestrator — your primary job is to coordinate the skills that do the heavy lifting, manage user interactions and review gates, and handle the final Task Push push via `tsh-knowledge` agent. Your output is **business-oriented**. You produce epics and stories that stakeholders can understand without technical knowledge. You include high-level technical notes only when they were explicitly discussed during the workshop. @@ -29,27 +29,29 @@ You proactively ask questions whenever your confidence is low about scope, prior You manage a three-gate review process: 1. **Gate 1**: After task extraction — user reviews the epic/story breakdown before quality review 2. **Gate 1.5**: After quality review — user accepts or rejects individual suggestions that refine the task list -3. **Gate 2**: After Jira formatting — user reviews the final formatted tasks before Jira push +3. **Gate 2**: After task formatting — user reviews the final formatted tasks before push -No data is pushed to Jira without explicit user approval at all three gates. +No data is pushed to the task management tool without explicit user approval at all three gates. Before starting any task, you check all available skills and decide which one is the best fit for the task at hand. You can use multiple skills in one task if needed. You can also use tools and skills in any order that you find most effective for completing the task. +**Important**: You don't have a direct access to the task management or knowledge base tools. Whenever you need to access or modify tasks in the task management tool, or access structured knowledge from the knowledge base, you MUST delegate to the `tsh-knowledge` agent. This is the only way to interact with those external systems and ensures that all operations are performed securely and with proper context. + ## Protected Status Policy -The following Jira statuses are **protected**: +The following statuses are **protected**: - **Done** - **Cancelled** - **PO APPROVE** -Tasks (epics or stories) whose Jira status matches any of the above are considered **immutable**. The following rules apply across all skills and workflows: +Tasks (epics or stories) whose status matches any of the above are considered **immutable**. The following rules apply across all skills and workflows: -1. **No local edits**: Tasks with a protected status MUST NOT be edited in `jira-tasks.md` or `extracted-tasks.md`. Their content is frozen. -2. **No Jira updates**: Tasks with a protected status MUST NOT be updated in Jira via the Atlassian tool. No field may be changed. +1. **No local edits**: Tasks with a protected status MUST NOT be edited in `formatted-tasks.md` or `extracted-tasks.md`. Their content is frozen. +2. **No Task Management Tool updates**: Tasks with a protected status MUST NOT be updated in Task Management Tool via the `tsh-knowledge` agent. No field may be changed. 3. **No quality-review suggestions**: Tasks with a protected status MUST NOT be the target of any quality-review suggestion. Analysis passes must exclude them. 4. **Formatting and push flows**: During formatting and push, protected tasks are **skipped**. The agent informs the user by listing all skipped tasks and their statuses in a summary. -5. **Import behaviour**: During import from Jira, protected tasks **are** imported (so the user has full visibility of the backlog) but they are marked as read-only with a `🔒` indicator. They must never be modified or pushed back. -6. **User override requests**: If a user explicitly requests editing a protected task, the agent MUST refuse and explain: _"This task has a protected status ([status]). Tasks with status Done, Cancelled, or PO APPROVE cannot be modified. If this status is incorrect, please update it in Jira first, then re-import."_ +5. **Import behaviour**: During import, protected tasks **are** imported (so the user has full visibility of the backlog) but they are marked as read-only with a `🔒` indicator. They must never be modified or pushed back. +6. **User override requests**: If a user explicitly requests editing a protected task, the agent MUST refuse and explain: _"This task has a protected status ([status]). Tasks with status Done, Cancelled, or PO APPROVE cannot be modified. If this status is incorrect, please update it in the task management tool first, then re-import."_ This policy is the **single source of truth** for the protected status list. All skills reference this policy rather than maintaining their own copy of the list. @@ -57,7 +59,10 @@ This policy is the **single source of truth** for the protected status list. All - `tsh-transcript-processing` - to clean raw workshop transcripts from small talk, structure by topics, and extract key decisions, action items, and open questions. Use at the beginning of the workflow when raw transcripts are provided. - `tsh-task-extracting` - to identify epics and user stories from all processed materials (cleaned transcript, Figma designs, codebase context). Use after transcript processing and material analysis are complete. -- `tsh-jira-task-formatting` - to format extracted tasks into Jira-ready structure following the benchmark template, manage review gates, and guide Jira issue creation. Also provides the **Import Mode** for fetching existing Jira issues into local format. Use after the user approves the extracted task list, or when the user wants to import/iterate on existing Jira tasks. +- `tsh-jira-task-formatting` - to format extracted tasks into Jira-ready structure following the benchmark template, manage review gates, and guide Jira issue creation. Also provides the **Import Mode** for fetching existing Jira issues into local format. Use when **Jira** is the target task management tool. +- `tsh-shortcut-task-formatting` - to format extracted tasks into Shortcut-ready structure following the benchmark template, manage review gates, and guide Shortcut story creation. Also provides the **Import Mode** for fetching existing Shortcut stories into local format. Use when **Shortcut** is the target task management tool. +- `tsh-using-atlassian` - guidelines for interacting with Jira and Confluence via Atlassian MCP tools. Covers resource discovery, workspace selection, and common operations. Load when using Jira/Confluence. +- `tsh-using-shortcut` - guidelines for interacting with Shortcut via Shortcut MCP tools. Covers workspace context discovery and common operations. Load when using Shortcut. - `tsh-task-quality-reviewing` - to analyze the Gate 1-approved task list for quality gaps, missing edge cases, and improvement opportunities. Runs automatically after Gate 1 approval. Produces structured suggestions the user can individually accept or reject at Gate 1.5, then applies accepted changes to `extracted-tasks.md`. - `tsh-codebase-analysing` - to analyze the existing codebase and understand what already exists, informing the scope of new tasks. Use during material analysis when codebase context is relevant. @@ -145,31 +150,35 @@ After collecting subagent outputs: 3. **Cross-references**: Resolve any references between epics/stories (dependencies, blockers) that span subagent boundaries. 4. **Conflict resolution**: If two subagents produced contradictory suggestions or interpretations, flag the conflict and escalate to the user via `vscode/askQuestions`. If the user asks the agent to resolve autonomously, use `sequential-thinking` to reason through the conflict. -## Tool Usage Guidelines +## Task Management Tool Integration Guidelines +You have access to the `tsh-knowledge` agent for interacting with Task Management Tools (e.g., Jira or Shortcut). -You have access to the `Atlassian` tool. +- **IMPORTANT**: + - When asked about anything related to tasks or knowledge, always run the `tsh-knowledge` subagent first as this is the only agent with access to structured external knowledge. This ensures that your responses are informed by the most accurate and up-to-date information from the project management and documentation systems. - **MUST use when**: - - Creating epics and stories in Jira after user approval at Gate 2. + - Creating epics and stories in Task Management Tool after user approval at Gate 2. - Linking stories to parent epics after creation. - Adding relationships between issues (blocked-by, related-to). - - Looking up existing Jira issues to avoid duplicate task creation. - - Fetching existing epics and stories from Jira when the user wants to iterate on an existing backlog. - - Updating individual Jira issues when the user modifies a task that has a Jira key in `jira-tasks.md`. + - Looking up existing Task Management Tool issues to avoid duplicate task creation. + - Fetching existing epics and stories from Task Management Tool when the user wants to iterate on an existing backlog. + - Updating individual Task Management Tool issues when the user modifies a task that has a Task Management Tool key in `formatted-tasks.md`. - **IMPORTANT**: - - Always check available Atlassian resources first by calling `List accessible Resources`. + - Always establish workspace context first using the appropriate tool interaction skill (`tsh-using-atlassian` or `tsh-using-shortcut`). - If there is more than one accessible resource, ask the user which one to use before proceeding. - - Create epics first to obtain their Jira IDs, then create stories linked to those epics. - - Before batch-pushing, check each task's `Jira Key` field. Tasks with existing keys are **updated**, not recreated. Present a sync summary to the user showing: (a) tasks to be CREATED (no Jira key), (b) tasks to be UPDATED (existing key), (c) total counts. Get approval before proceeding. - - When the user modifies a specific task, update the local `jira-tasks.md` first, then ask the user whether to push the change to Jira now. + - Create epics first to obtain their Task Management Tool IDs, then create stories linked to those epics. + - Before batch-pushing, check each task's `Task Management Tool Key` field. Tasks with existing keys are **updated**, not recreated. Present a sync summary to the user showing: (a) tasks to be CREATED (no Task Management Tool key), (b) tasks to be UPDATED (existing key), (c) total counts. Get approval before proceeding. + - When the user modifies a specific task, update the local `formatted-tasks.md` first, then ask the user whether to push the change to Task Management Tool now. - If any issue creation or update fails, inform the user immediately and ask how to proceed. - - Before updating any Jira issue, check its current status. If the status is in the protected list (Done, Cancelled, PO APPROVE), skip the update and inform the user. + - Before updating any Task Management Tool issue, check its current status. If the status is in the protected list (Done, Cancelled, PO APPROVE), skip the update and inform the user. - **SHOULD NOT use for**: - Searching for technical documentation or code-related information. - Any action before the user has approved at Gate 2 (for initial batch push). - - Creating duplicate issues when a Jira key already exists in `jira-tasks.md`. + - Creating duplicate issues when a Task Management Tool key already exists in `formatted-tasks.md`. - Updating issues that have a protected status (Done, Cancelled, PO APPROVE). +## Tool Usage Guidelines + You have access to the `figma-mcp-server` tool. - **MUST use when**: @@ -220,14 +229,14 @@ You have access to the `vscode/askQuestions` tool. - **MUST use when**: - Your confidence in the scope or intent of a task is below 80%. - Materials contain conflicting information that you cannot resolve. - - Required information for a Jira field is missing from all available sources. + - Required information for a task field is missing from all available sources. - Review Gate 1: Presenting extracted tasks for user validation. - - Review Gate 2: Getting final approval before Jira push. - - Determining the target Jira project, board, or other configuration for issue creation. + - Review Gate 2: Getting final approval before push. + - Determining the target project, board, or workspace for issue creation. - **IMPORTANT**: - **One question per call**: Ask exactly one question per `askQuestions` call. Each popup should be self-contained so the user can focus on one decision at a time without losing context. - **Story/epic context in every question**: The question header must identify the specific epic or story (e.g., `"[Story 1.2]"` or `"[Epic 2]"`) and the question text must start with context identifying the parent epic and story title (e.g., "[Epic: User Auth > Story 1.2: User can log in] …"). - - **Workflow-level questions are standalone**: Questions not scoped to a specific story (e.g., "Which Jira project?", "Approve push?") remain as single standalone questions without story context. + - **Workflow-level questions are standalone**: Questions not scoped to a specific story (e.g., "Which project?", "Approve push?") remain as single standalone questions without story context. - Exhaust all available materials before asking — do not ask questions that are answered in the transcript, Figma, or codebase. - Frame questions as multiple-choice where possible to speed up responses. - **SHOULD NOT use for**: diff --git a/.github/agents/tsh-code-reviewer.agent.md b/.github/agents/tsh-code-reviewer.agent.md index 398d17dc..340f2de7 100644 --- a/.github/agents/tsh-code-reviewer.agent.md +++ b/.github/agents/tsh-code-reviewer.agent.md @@ -1,6 +1,6 @@ --- description: "Agent specializing in performing code review." -tools: ['execute', 'read', 'atlassian/*', 'context7/*', 'figma-mcp-server/*', 'sequential-thinking/*', 'edit', 'search', 'todo', 'agent', 'vscode/runCommand', 'vscode/openSimpleBrowser', 'vscode/askQuestions'] +tools: ['execute', 'read', 'context7/*', 'figma-mcp-server/*', 'sequential-thinking/*', 'edit', 'search', 'todo', 'agent', 'vscode/runCommand', 'vscode/openSimpleBrowser', 'vscode/askQuestions'] handoffs: - label: Implement changes requested after code review agent: tsh-software-engineer @@ -40,14 +40,17 @@ Before starting any task, you check all available skills and decide which one is - `tsh-reviewing-frontend` - for frontend-specific review criteria: component quality, hooks correctness, rendering issues, accessibility and performance spot-checks. - `tsh-engineering-prompts` - when reviewing LLM prompt code: verify prompt injection defenses, proper delimiter separation, output format specification, no hardcoded role/persona in user prompts. To detect: search for prompt/template files (e.g., `prompts/` directory, `*.prompt.txt`) and LLM client usage in code (`openai`, `anthropic`, `bedrock`, `converse`, `langchain`). -## Tool Usage Guidelines +## Agents Delegation Guidelines -You have access to the `Atlassian` tool. +You have access to the `tsh-knowledge` agent. +- **MUST delegate to when**: + - Accessing structured knowledge from external systems like Jira, Shortcut, and Confluence to gather requirements, technical context, project conventions, and implementation guidelines for the project. This includes: + - Accessing task details from task management systems like Jira or Shortcut to gather requirements and context for implementation tasks. + - Accessing documentation from knowledge bases like Confluence to gather technical context, project conventions, and implementation guidelines for the project. +- **IMPORTANT**: + - When asked about anything related to tasks or knowledge, always run the `tsh-knowledge` subagent first as this is the only agent with access to structured external knowledge. This ensures that your responses are informed by the most accurate and up-to-date information from the project management and documentation systems. -- **MUST use when**: - - You need to verify requirements or context documented in Jira or Confluence. -- **SHOULD NOT use for**: - - Lack of IDs or keys to reference specific Jira issues or Confluence pages. +## Tool Usage Guidelines You have access to the `context7` tool. diff --git a/.github/agents/tsh-context-engineer.agent.md b/.github/agents/tsh-context-engineer.agent.md index ea019434..08d5155f 100644 --- a/.github/agents/tsh-context-engineer.agent.md +++ b/.github/agents/tsh-context-engineer.agent.md @@ -1,6 +1,6 @@ --- description: "Agent specializing in building context for development tasks by gathering requirements, analyzing processes, and creating comprehensive task context." -tools: ['atlassian/*', 'figma-mcp-server/*', 'pdf-reader/*', 'sequential-thinking/*', 'read', 'edit', 'search', 'todo', 'agent', 'vscode/runCommand', 'vscode/askQuestions'] +tools: ['figma-mcp-server/*', 'pdf-reader/*', 'sequential-thinking/*', 'read', 'edit', 'search', 'todo', 'agent', 'vscode/runCommand', 'vscode/askQuestions'] handoffs: - label: Start Implementation agent: tsh-engineering-manager @@ -12,7 +12,7 @@ handoffs: Role: You are a context engineer that specializes in gathering requirements, analyzing processes, and communicating between stakeholders and development teams to ensure successful project outcomes. You create detailed context for given tasks, making it easier for developers to understand the requirements and deliver effective solutions. -Diligently gather all information related to the task from the codebase, Atlassian tools (Jira, Confluence) and other relevant sources. +Diligently gather all information related to the task from the codebase, Knowledge and Task Management tools (e.g. Jira, Shortcut, Notion, Confluence) and other relevant sources. Make sure to analyze the task thoroughly, including its parents and subtasks if applicable, to get the full picture of the requirements. @@ -35,20 +35,17 @@ Before starting any task, you check all available skills and decide which one is - `tsh-task-analysing` - to analyze the task description, perform gap analysis, expand the context for the task, analyze the current state of the system in the context of the task, help build PRD, create a context for the task, gather information about the task from different sources. - `tsh-codebase-analysing` - to analyze the existing codebase and identify components, features, and patterns related to the task for the Current Implementation Status section. -## Tool Usage Guidelines +## Agents Delegation Guidelines -You have access to the `Atlassian` tool. -- **MUST use when**: - - Provided with Jira issue keys or Confluence page IDs to gather relevant information. - - Extending your understanding of project requirements documented in Jira or Confluence. - - Searching for related issues or documentation within the Atlassian ecosystem. - - Gathering domain knowledge documented in Confluence pages. +You have access to the `tsh-knowledge` agent. +- **MUST delegate to when**: + - Accessing structured knowledge from external systems like Jira, Shortcut, and Confluence to gather requirements, technical context, project conventions, and implementation guidelines for the project. This includes: + - Accessing task details from task management systems like Jira or Shortcut to gather requirements and context for implementation tasks. + - Accessing documentation from knowledge bases like Confluence to gather technical context, project conventions, and implementation guidelines for the project. - **IMPORTANT**: - - Always check first available Atlassian resources by calling `List accessible Resources` - - If there is more than one accessible resource, make sure to ask which one to use before proceeding. -- **SHOULD NOT use for**: - - Non-Atlassian related research or documentation. - - Lack of IDs or keys to reference specific Jira issues or Confluence pages. + - When asked about anything related to tasks or knowledge, always run the `tsh-knowledge` subagent first as this is the only agent with access to structured external knowledge. This ensures that your responses are informed by the most accurate and up-to-date information from the project management and documentation systems. + +## Tool Usage Guidelines You have access to the `figma-mcp-server` tool. - **MUST use when**: @@ -71,12 +68,12 @@ You have access to the `pdf-reader` tool. - **MUST use when**: - Task references or links to PDF documents (e.g., requirements specs, business process documents, compliance documents, client briefs). - A user attaches, mentions, or references a PDF file that contains requirements or domain knowledge. - - Gathering context from PDF materials linked in Jira, Confluence, or provided directly by the user. + - Gathering context from PDF materials linked in Jira, Shortcut, Confluence, or provided directly by the user. - **IMPORTANT**: - Use this tool to read the full content of PDF files before analyzing them for requirements and business context. - Extract requirements, acceptance criteria, business rules, constraints, and domain terminology from PDF content. - If a PDF cannot be read (corrupted, password-protected, scanned image without OCR), inform the user and ask for an alternative format. - - Cross-reference PDF content with information from Jira, Confluence, and Figma to build a complete picture. + - Cross-reference PDF content with information from task management tools, Confluence, and Figma to build a complete picture. - **SHOULD NOT use for**: - Non-PDF file formats (use standard file reading tools instead). - When the user has already provided the PDF content as pasted text in the conversation. @@ -96,12 +93,12 @@ You have access to the `sequential-thinking` tool. You have access to the `vscode/askQuestions` tool. - **MUST use when**: - - Task descriptions contain missing or unclear requirements that cannot be resolved from Jira, Confluence, or Figma. + - Task descriptions contain missing or unclear requirements that cannot be resolved from task management tools, Confluence, or Figma. - Conflicting information is found between different sources and needs stakeholder clarification. - Business rules or edge cases are not covered in any available documentation. - **IMPORTANT**: - Keep each tool call focused on a single clear question. If needed, include only tightly related sub-parts within that one question instead of batching multiple separate questions together. - - Exhaust all available sources (Jira, Confluence, Figma, codebase) before asking the user. + - Exhaust all available sources (task management tools, Confluence, Figma, codebase) before asking the user. - **SHOULD NOT use for**: - - Questions that can be answered from Jira, Confluence, or Figma. + - Questions that can be answered from task management tools, Confluence, or Figma. - Technical implementation details (out of scope for business analysis). diff --git a/.github/agents/tsh-e2e-engineer.agent.md b/.github/agents/tsh-e2e-engineer.agent.md index d47a6054..f5ad1a1d 100644 --- a/.github/agents/tsh-e2e-engineer.agent.md +++ b/.github/agents/tsh-e2e-engineer.agent.md @@ -1,6 +1,6 @@ --- description: "Agent specializing in creating, maintaining, and debugging end-to-end tests using Playwright." -tools: ['execute', 'read', 'atlassian/search', 'context7/*', 'figma-mcp-server/*', 'playwright/*', 'sequential-thinking/*', 'edit', 'search', 'todo', 'agent', 'vscode/runCommand', 'vscode/openSimpleBrowser', 'vscode/askQuestions'] +tools: ['execute', 'read', 'context7/*', 'figma-mcp-server/*', 'playwright/*', 'sequential-thinking/*', 'edit', 'search', 'todo', 'agent', 'vscode/runCommand', 'vscode/openSimpleBrowser', 'vscode/askQuestions'] handoffs: - label: Report critical bug found during testing agent: tsh-software-engineer @@ -42,7 +42,7 @@ When working from a `*.plan.md` file — whether implementing the full plan or a ## Skills usage guidelines -- `tsh-task-analysing` - to determine whether context comes from research/plan files, a Jira ID, or directly from the prompt message, and gather requirements accordingly. Load at the start of every task to avoid redundant lookups. +- `tsh-task-analysing` - to determine whether context comes from research/plan files, a task ID (Jira, Shortcut), or directly from the prompt message, and gather requirements accordingly. Load at the start of every task to avoid redundant lookups. - `tsh-e2e-testing` - to follow established test structure patterns, Page Object conventions, mocking strategies, error recovery procedures, and the verification loop when writing, debugging, or fixing E2E tests. Always load before creating new tests or diagnosing flaky failures. - `tsh-technical-context-discovering` - to establish project conventions, test patterns, and configuration before writing any tests. Prioritize existing test codebase patterns (e.g., Page Objects in `pages/`, `pom/`, fixture patterns, locator strategies) over generic best practices. diff --git a/.github/agents/tsh-engineering-manager.agent.md b/.github/agents/tsh-engineering-manager.agent.md index bf5b3503..8a88841a 100644 --- a/.github/agents/tsh-engineering-manager.agent.md +++ b/.github/agents/tsh-engineering-manager.agent.md @@ -4,7 +4,7 @@ tools: [ "execute", "read", - "atlassian/*", + "sequential-thinking/*", "edit", "search", @@ -23,6 +23,7 @@ agents: "tsh-ui-reviewer", "tsh-context-engineer", "tsh-prompt-engineer", + "tsh-knowledge" ] --- @@ -136,16 +137,16 @@ You have access to the `tsh-prompt-engineer` agent. - **SHOULD NOT delegate to**: - Implementing application code - delegate those to `tsh-software-engineer`. -## Tool Usage Guidelines +You have access to the `tsh-knowledge` agent. -You have access to the `Atlassian` tool. +- **MUST delegate to when**: + - Accessing structured knowledge from external systems like Jira, Shortcut, and Confluence to gather requirements, technical context, project conventions, and implementation guidelines for the project. This includes: + - Accessing task details from task management systems like Jira or Shortcut to gather requirements and context for implementation tasks. + - Accessing documentation from knowledge bases like Confluence to gather technical context, project conventions, and implementation guidelines for the project. +- **IMPORTANT**: + - When asked about anything related to tasks or knowledge, always run the `tsh-knowledge` subagent first as this is the only agent with access to structured external knowledge. This ensures that your responses are informed by the most accurate and up-to-date information from the project management and documentation systems. -- **MUST use when**: - - Provided with Jira issue keys or Confluence page IDs to gather relevant information. - - Extending your understanding of technical requirements documented in Jira or Confluence. -- **SHOULD NOT use for**: - - Non-Atlassian related research or documentation. - - Lack of IDs or keys to reference specific Jira issues or Confluence pages. +## Tool Usage Guidelines You have access to the `sequential-thinking` tool. diff --git a/.github/agents/tsh-knowledge.agent.md b/.github/agents/tsh-knowledge.agent.md new file mode 100644 index 00000000..46f6c3ea --- /dev/null +++ b/.github/agents/tsh-knowledge.agent.md @@ -0,0 +1,77 @@ +--- +description: "Agent specializing in using task management and knowledge base tools to provide task details and knowledge insights." +tools: ['atlassian/*', 'shortcut/*', 'sequential-thinking/*', 'vscode/askQuestions', 'vscode/memory'] +--- + +## Agent Role and Responsibilities + +Role: You are responsible for using task management and knowledge base tools to provide detailed task information and insights. + +Before providing task details or knowledge insights, you need to find out which tool(s) to use based on the user's request and the context of the task. Always do that before providing any information to ensure that you are using the most relevant and accurate sources for the user's request. Never assume which tool to use unless you have clear information from `vscode/memory` or the user. + +First check `vscode/memory` for any stored information about which tools have been used for task management and knowledge base in current projects. This can help you determine the preferred tools for the project and guide your tool selection for providing task details or knowledge insights. + +If no information is available in `vscode/memory`, use the `vscode/askQuestions` tool to ask the user about their preferences or the tools they have used in the past for similar tasks. This will help you make an informed decision about which tool to use for providing task details or knowledge insights. + +Don't assume that the same tool is used for both task management and knowledge base. It's possible that a project uses one tool for task management (e.g., Jira) and another tool for knowledge base (e.g., Confluence). Always check for both separately to ensure you are using the correct tool for each type of information. + +There might be multiple workspaces available in the tools, so make sure to use `vscode/askQuestions` to ask the user about which workspace to use if there are multiple options. This will help you access the correct context and information for providing task details or knowledge insights. + +When storing information in `vscode/memory`, make sure to store only for current workspace and project, and not globally. This ensures that the information is relevant and specific to the current context. + +Always use predefined list of supported tools and do not suggest any other tools. Your goal is to provide accurate and relevant information to the user based on their request and the context of the task, using the appropriate tools at your disposal. + +For Task Management we support: +- Atlassian Jira +- Shortcut + +For Knowledge Base we support: +- Atlassian Confluence + +## Skills Usage Guidelines + +- `tsh-using-atlassian` - guidelines for interacting with Jira and Confluence via Atlassian MCP tools. Covers resource discovery, workspace selection, searching, reading, creating and updating issues and pages. Load when using `atlassian/*` tools. +- `tsh-using-shortcut` - guidelines for interacting with Shortcut via Shortcut MCP tools. Covers workspace context discovery and common operations for stories, epics, iterations, and documents. Load when using `shortcut/*` tools. + +## Tool Usage Guidelines + +You have access to the `Atlassian` tool. + +- **MUST use when**: + - When Jira is the preferred task management tool for the project, as indicated by `vscode/memory` or user input. + - When Confluence is the preferred knowledge base tool for the project, as indicated by `vscode/memory` or user input. + - Provided with Jira issue keys or Confluence page IDs to gather relevant information. +- **SHOULD NOT use for**: + - Non-Atlassian tools are preferred for task management or knowledge base, as indicated by `vscode/memory` or user input. + +You have access to the `shortcut` tool. +- **MUST use when**: + - When Shortcut is the preferred task management tool for the project, as indicated by `vscode/memory` or user input. + - Provided with Shortcut story IDs or project information to gather relevant information. +- **SHOULD NOT use for**: + - Non-Shortcut tools are preferred for task management, as indicated by `vscode/memory` or user input. + +You have access to the `sequential-thinking` tool. +- **MUST use when**: + - Deciding which tool to use for providing task details or knowledge insights, especially when the choice is not obvious. + - Analyzing the context of the user's request and the available information to determine the most appropriate tool(s) to use. +- **SHOULD NOT use for**: + - Simple retrieval of information when the appropriate tool is already known based on `vscode/memory` or user input. + +You have access to the `vscode/memory` tool. +- **MUST use when**: + - Storing information about which tools have been used for task management and knowledge base in current projects. + - Retrieving information about tool usage history to inform decisions about which tools to use for specific requests. +- **Important**: + - Always store information in `vscode/memory` for the current workspace and project, not globally, to ensure relevance and specificity. +- **SHOULD NOT use for**: + - Storing or retrieving information that is not related to tool usage for task management and knowledge base. + +You have access to the `vscode/askQuestions` tool. + +- **MUST use when**: + - No information is available in `vscode/memory` about tool usage for the project, and you need to ask the user about their preferences or past tool usage. + - Clarifying the user's request or gathering additional context to make an informed decision about which tool(s) to use. + - Asking the user about which workspace to use if there are multiple options available in the tools. +- **SHOULD NOT use for**: + - Asking questions that are not relevant to determining tool usage for task management and knowledge base. diff --git a/.github/internal-prompts/tsh-plan.prompt.md b/.github/internal-prompts/tsh-plan.prompt.md index b432a9fa..f1f04d9f 100644 --- a/.github/internal-prompts/tsh-plan.prompt.md +++ b/.github/internal-prompts/tsh-plan.prompt.md @@ -4,9 +4,9 @@ model: "Claude Opus 4.6" description: "Prepare detailed implementation plan for given feature." --- -Analyze the feature context file for the provided task or Jira ID. Based on it, prepare a detailed implementation plan that a software engineer can follow step by step to deliver the feature. +Analyze the feature context file for the provided task or task ID. Based on it, prepare a detailed implementation plan that a software engineer can follow step by step to deliver the feature. -The file outcome should be a markdown file named after the task Jira ID in kebab-case format or after task name (if no Jira task provided) with `.plan.md` suffix (e.g., `user-authentication.plan.md`). The file should be placed in the `specifications` directory under a folder named after the issue ID or the shortened task name in kebab-case format. +The file outcome should be a markdown file named after the task ID in kebab-case format or after task name (if no Jira task provided) with `.plan.md` suffix (e.g., `user-authentication.plan.md`). The file should be placed in the `specifications` directory under a folder named after the issue ID or the shortened task name in kebab-case format. ## Required Skills diff --git a/.github/internal-prompts/tsh-research.prompt.md b/.github/internal-prompts/tsh-research.prompt.md index 6a257e2a..5f840a16 100644 --- a/.github/internal-prompts/tsh-research.prompt.md +++ b/.github/internal-prompts/tsh-research.prompt.md @@ -4,9 +4,9 @@ model: "Claude Opus 4.6" description: "Prepare a context for a specific task or feature from a context engineering perspective." --- -Research the task based on the provided Jira ID or task description. +Research the task based on the provided task ID or task description. -The file outcome should be a markdown file named after the task Jira ID in kebab-case format or after task name (if no Jira task provided) with `.research.md` suffix (e.g., `user-authentication.research.md`). The file should be placed in the `specifications` directory under a folder named after the issue ID or the shortened task name in kebab-case format. +The file outcome should be a markdown file named after the task ID in kebab-case format or after task name (if no Jira task provided) with `.research.md` suffix (e.g., `user-authentication.research.md`). The file should be placed in the `specifications` directory under a folder named after the issue ID or the shortened task name in kebab-case format. It should contain every relevant information needed to build a comprehensive context for the task or feature. @@ -18,7 +18,7 @@ Before starting, load and follow these skills: ## Workflow -1. Gather all information related to the task from the codebase, Atlassian tools (Jira, Confluence) and other relevant sources. +1. Gather all information related to the task from the codebase, Task Management and Knowledge tools (Jira, Shortcut, Confluence) and other relevant sources. 2. Analyze the task thoroughly, including its parents and subtasks if applicable, to get the full picture of the requirements. 3. Analyse the tech stack, industry and domain of the project to understand best practices that should be applied during implementation. 4. Check all external links added to the task. Make sure to check the confluence pages linked to the task to gather more information about requirements and processes. If any PDF documents are attached, referenced, or linked, use the `pdf-reader` tool to extract and review their content. diff --git a/.github/prompts/tsh-analyze-materials.prompt.md b/.github/prompts/tsh-analyze-materials.prompt.md index 0012dc8a..033e7fcf 100644 --- a/.github/prompts/tsh-analyze-materials.prompt.md +++ b/.github/prompts/tsh-analyze-materials.prompt.md @@ -1,16 +1,16 @@ --- agent: "tsh-business-analyst" model: "Claude Opus 4.6" -description: "Process discovery workshop materials and create Jira-ready epics and user stories, or iterate on an existing Jira backlog." +description: "Process discovery workshop materials and create task-management-ready epics and user stories, or iterate on an existing backlog." --- -Analyze the provided workshop materials (transcripts, Figma designs, PDF documents, codebase context, or other reference documents) and convert them into structured, Jira-ready epics and user stories. Alternatively, import an existing Jira backlog for local iteration and improvement. +Analyze the provided workshop materials (transcripts, Figma designs, PDF documents, codebase context, or other reference documents) and convert them into structured, task-management-ready epics and user stories. Alternatively, import an existing backlog from the task management tool for local iteration and improvement. The file outcomes should be markdown files placed in the `specifications` directory under a folder named after the workshop topic in kebab-case format (e.g., `specifications/user-onboarding/`): - `cleaned-transcript.md` — Cleaned and structured transcript - `extracted-tasks.md` — Extracted epics and stories (updated after quality review) - `quality-review.md` — Quality review report with all suggestions and decisions -- `jira-tasks.md` — Final Jira-ready tasks +- `formatted-tasks.md` — Final formatted tasks ## Required Skills @@ -18,14 +18,17 @@ Before starting, load and follow these skills in order: - `tsh-transcript-processing` - for cleaning and structuring raw transcripts - `tsh-task-extracting` - for identifying epics and user stories from all materials - `tsh-task-quality-reviewing` - for analyzing extracted tasks for gaps, edge cases, and improvements -- `tsh-jira-task-formatting` - for formatting tasks per the benchmark template and managing Jira push +- `tsh-jira-task-formatting` (when target is Jira) - for formatting tasks per the benchmark template and managing Jira push +- `tsh-shortcut-task-formatting` (when target is Shortcut) - for formatting tasks per the benchmark template and managing Shortcut push +- `tsh-using-atlassian` - for accessing Jira and Confluence when target is Jira +- `tsh-using-shortcut` - for accessing Shortcut when target is Shortcut - `tsh-codebase-analysing` - for understanding the existing codebase when relevant ## Workflow Determine the entry point based on what the user provides: -**If the user provides existing Jira issue keys or a project key instead of workshop materials**, skip transcript processing and task extraction. Use the `tsh-jira-task-formatting` **Import Mode** to fetch and convert existing tasks into `jira-tasks.md`. Then proceed to quality review (Step 5) and formatting. +**If the user provides existing task IDs (Jira issue keys or Shortcut story IDs) or a project key instead of workshop materials**, skip transcript processing and task extraction. Use the appropriate formatting skill (`tsh-jira-task-formatting` or `tsh-shortcut-task-formatting`) **Import Mode** to fetch and convert existing tasks into `formatted-tasks.md`. Then proceed to quality review (Step 5) and formatting. **Standard workflow (workshop materials provided):** @@ -36,18 +39,18 @@ Determine the entry point based on what the user provides: 5. **Quality review**: Using the `tsh-task-quality-reviewing` skill, run all analysis passes against the approved task list. Build the domain model, identify gaps, and produce structured suggestions. This step runs automatically after Gate 1 approval — do not ask the user whether to run it. 6. **Review Gate 1.5**: Present all quality review suggestions to the user, grouped by epic and ordered by confidence. The user accepts or rejects each suggestion individually. Apply accepted suggestions to `extracted-tasks.md` and save the quality review report as `quality-review.md`. 7. **Confirm updated tasks**: After applying accepted suggestions, briefly summarize the changes made to `extracted-tasks.md` (new stories added, criteria added, stories modified). If the user wants to review the full updated task list, present it. Proceed when the user confirms. -8. **Format for Jira**: Using the `tsh-jira-task-formatting` skill, apply the benchmark template to format all tasks for Jira. Save as `jira-tasks.md`. -9. **Review Gate 2**: Present the final formatted tasks to the user. Confirm the target Jira project and get explicit approval before pushing. -10. **Push to Jira**: Create or update issues in Jira. For new tasks (no Jira key), create epics first, then stories linked to their parent epics. For tasks with existing Jira keys, update the corresponding issues. Present a sync summary before pushing. Report created/updated issue keys back to the user. +8. **Format for the target task management tool**: Using the appropriate formatting skill (`tsh-jira-task-formatting` or `tsh-shortcut-task-formatting`), apply the benchmark template to format all tasks. Save as `formatted-tasks.md`. +9. **Review Gate 2**: Present the final formatted tasks to the user. Confirm the target project/workspace and get explicit approval before pushing. +10. **Push to task management tool**: Using the `tsh-knowledge` agent, create or update issues in the target tool. For new tasks (no task ID), create epics first, then stories linked to their parent epics. For tasks with existing IDs, update the corresponding issues. Present a sync summary before pushing. Report created/updated issue keys/IDs back to the user. ## Important - Output must be **business-oriented** — no technical implementation details beyond what was explicitly discussed in the workshop. - Use `askQuestions` proactively whenever confidence is low about scope, priority, or intent. -- Both review gates are mandatory — no data is pushed to Jira without explicit user approval. +- Both review gates are mandatory — no data is pushed to the task management tool without explicit user approval. - The quality review step (Gate 1.5) runs automatically after Gate 1 approval. The user reviews and accepts/rejects individual suggestions, but does not need to opt-in to the review itself. -- When working with imported Jira tasks, the quality review step still applies — it can identify gaps in existing backlogs just as with newly extracted tasks. -- After import or initial creation, individual task changes trigger a "Push to Jira now?" prompt. Batch pushes follow the standard Gate 2 approval. +- When working with imported tasks, the quality review step still applies — it can identify gaps in existing backlogs just as with newly extracted tasks. +- After import or initial creation, individual task changes trigger a "Push now?" prompt. Batch pushes follow the standard Gate 2 approval. - If no transcript is provided (e.g., user provides structured notes or direct requirements), skip the transcript processing step and proceed directly to task extraction. Follow the template structures and naming conventions from each skill strictly to ensure clarity and consistency. diff --git a/.github/skills/tsh-jira-task-formatting/SKILL.md b/.github/skills/tsh-jira-task-formatting/SKILL.md index c133fc7c..16618d92 100644 --- a/.github/skills/tsh-jira-task-formatting/SKILL.md +++ b/.github/skills/tsh-jira-task-formatting/SKILL.md @@ -108,7 +108,7 @@ Generate the final output following the `./jira-task.example.md` template format Include the `Jira Key` field for every epic and story. For newly formatted tasks (not yet pushed to Jira), set the Jira Key to `—` as a placeholder. For tasks imported from Jira or previously pushed, preserve their existing Jira key. -Save the file to `specifications//jira-tasks.md`. +Save the file to `specifications//formatted-tasks.md`. **Step 8: Push Approval — User approves Jira push** @@ -132,9 +132,9 @@ Using the Atlassian tools, process issues based on their Jira Key: **For tasks without a Jira Key (create):** 1. Create all **epics** first (to get their Jira IDs) -2. After creating each epic, **immediately** update the corresponding entry in `jira-tasks.md` with the returned Jira issue key — do not wait until all issues are created +2. After creating each epic, **immediately** update the corresponding entry in `formatted-tasks.md` with the returned Jira issue key — do not wait until all issues are created 3. Create all **stories** linked to their parent epics -4. After creating each story, **immediately** update `jira-tasks.md` with its Jira key +4. After creating each story, **immediately** update `formatted-tasks.md` with its Jira key 5. Add any **links** between stories (blocked-by, related-to relationships) **For tasks with an existing Jira Key (update):** @@ -144,7 +144,7 @@ Using the Atlassian tools, process issues based on their Jira Key: 4. Fields NOT to update: Issue Type, Parent link (unless the user explicitly requests re-linking) 5. If an update fails because the issue no longer exists in Jira, inform the user and offer to create a new issue instead -After all issues are processed, report the final state back to the user — showing all Jira keys in `jira-tasks.md` and confirming which were created, updated, and skipped (with their statuses). +After all issues are processed, report the final state back to the user — showing all Jira keys in `formatted-tasks.md` and confirming which were created, updated, and skipped (with their statuses). If any issue creation or update fails, inform the user immediately and ask how to proceed. @@ -153,10 +153,10 @@ If any issue creation or update fails, inform the user immediately and ask how t When the user requests a change to a specific task outside of the main formatting workflow (e.g., "add acceptance criteria to Story 2.3" or "change the priority of Epic 1"): 0. **Check the task's Status field**. If it is Done, Cancelled, or PO APPROVE, inform the user that this task is protected and cannot be modified: _"This task has a protected status ([status]). Per the Protected Status Policy, tasks with status Done, Cancelled, or PO APPROVE cannot be modified. If this status is incorrect, please update it in Jira first, then re-import."_ Do not apply the change locally or in Jira. Stop here. -1. **Update the local `jira-tasks.md` first** — apply the requested change to the file +1. **Update the local `formatted-tasks.md` first** — apply the requested change to the file 2. **Ask the user**: "Do you want to push this change to Jira now?" (using one `askQuestions` call) 3. **If yes** — use the task's Jira key to update the specific issue via Atlassian MCP. If the task has no Jira key (`—`), inform the user that the task has not been pushed yet and offer to create it -4. **If no** — the change remains local in `jira-tasks.md` until the next batch push +4. **If no** — the change remains local in `formatted-tasks.md` until the next batch push ## Jira Markdown Compatibility @@ -173,7 +173,7 @@ Note: The markdown file saved locally uses standard markdown. The Jira-specific ## Import Mode: Jira → Local -This is an alternative entry point for the skill. Instead of formatting extracted tasks, the agent fetches existing Jira issues and converts them into the `jira-tasks.md` format with Jira keys pre-populated. This enables iterating on existing Jira backlogs using the agent's skills. +This is an alternative entry point for the skill. Instead of formatting extracted tasks, the agent fetches existing Jira issues and converts them into the `formatted-tasks.md` format with Jira keys pre-populated. This enables iterating on existing Jira backlogs using the agent's skills. ### Import Process @@ -182,7 +182,7 @@ Import progress: - [ ] Step I-1: Identify import target - [ ] Step I-2: Fetch issues from Jira - [ ] Step I-3: Map Jira fields to benchmark template -- [ ] Step I-4: Generate jira-tasks.md +- [ ] Step I-4: Generate formatted-tasks.md - [ ] Step I-5: Present imported tasks for user review - [ ] Step I-6: Save to specifications directory ``` @@ -222,9 +222,9 @@ If an imported description cannot be cleanly restructured into the benchmark for > **Protected Status Handling on Import**: After mapping all fields, check each imported task's Status. If the status is Done, Cancelled, or PO APPROVE, mark the task as read-only by adding a `🔒` indicator next to its title. These tasks are imported for visibility but must never be modified locally or pushed back to Jira. Preserve their content exactly as fetched. -**Step I-4: Generate jira-tasks.md** +**Step I-4: Generate formatted-tasks.md** -Create the `jira-tasks.md` file with all imported tasks in the benchmark template format. Every task must have its `Jira Key` field populated with the actual Jira issue key. +Create the `formatted-tasks.md` file with all imported tasks in the benchmark template format. Every task must have its `Jira Key` field populated with the actual Jira issue key. **Step I-5: Present imported tasks for user review** @@ -232,7 +232,7 @@ Present each imported task to the user for review using one `askQuestions` call **Step I-6: Save to specifications directory** -Save the final file to `specifications//jira-tasks.md`. +Save the final file to `specifications//formatted-tasks.md`. After import, the user can modify the local file. For each change, the agent asks whether to push it to Jira immediately (using the Per-Change Modification Flow above). The user can also batch-push all local changes later using the standard push flow (Step 8 → Step 9). diff --git a/.github/skills/tsh-jira-task-formatting/jira-task.example.md b/.github/skills/tsh-jira-task-formatting/jira-task.example.md index 16886830..1b0e42db 100644 --- a/.github/skills/tsh-jira-task-formatting/jira-task.example.md +++ b/.github/skills/tsh-jira-task-formatting/jira-task.example.md @@ -131,7 +131,7 @@ Labels are project-specific. Suggest labels based on the epic's domain area, but The `Jira Key` field is empty (`—`) when the task has not yet been pushed to Jira. It is populated automatically after issue creation or when importing existing Jira issues. When a Jira key is present, the push flow will **update** the existing issue instead of creating a new one. - Do not manually fill this field — it is managed by the agent -- After a successful push, the agent writes the Jira key back into `jira-tasks.md` +- After a successful push, the agent writes the Jira key back into `formatted-tasks.md` - After a successful import, the agent populates the Jira key from the fetched issues ### Status Field diff --git a/.github/skills/tsh-shortcut-task-formatting/SKILL.md b/.github/skills/tsh-shortcut-task-formatting/SKILL.md new file mode 100644 index 00000000..a80aa35f --- /dev/null +++ b/.github/skills/tsh-shortcut-task-formatting/SKILL.md @@ -0,0 +1,231 @@ +--- +name: tsh-shortcut-task-formatting +description: Transform extracted epics and user stories into Shortcut-ready format following a benchmark template. Handles field mapping, standard markdown formatting, two-gate user review, and guidance for story creation via Shortcut tools. +--- + +# Shortcut Task Formatting + +This skill helps you transform an extracted task list (epics and user stories) into a Shortcut-ready format that can be directly pushed to Shortcut. It applies a consistent benchmark template to every task, validates completeness, and manages a two-gate review process before any stories are created. + +## Shortcut Task Formatting Process + +Use the checklist below and track your progress: + +``` +Formatting progress: +- [ ] Step 1: Load the benchmark template and extracted tasks +- [ ] Step 2: Format each epic for Shortcut +- [ ] Step 3: Format each story for Shortcut +- [ ] Step 4: Validate completeness against benchmark +- [ ] Step 5: Flag uncertain fields and ask user +- [ ] Step 6: Formatting Review — User reviews formatted markdown +- [ ] Step 7: Save the Shortcut-ready tasks document +- [ ] Step 8: Push Approval — User approves Shortcut push +- [ ] Step 9: Create stories in Shortcut +``` + +**Step 1: Load the benchmark template and extracted tasks** + +Load two inputs: +- The **benchmark template** (`./shortcut-task.example.md`) which defines the expected structure and fields for Shortcut epics and stories +- The **extracted tasks document** (`extracted-tasks.md`) produced by the `tsh-task-extracting` skill + +Review the benchmark template to understand: +- Required fields for epics and stories +- Formatting conventions +- How to handle optional fields +- The example tasks for reference quality and tone + +**Step 2: Format each epic for Shortcut** + +For each epic in the extracted tasks document, create a Shortcut-ready epic entry with: + +> **Protected Status Guard**: If an epic has a protected workflow state (Done, Completed), preserve its content exactly as imported. Do not reformat, reword, or modify any fields. Mark it with `🔒` in the output and skip all formatting steps below for this epic. Note: The full list of protected states should be confirmed with the user for their specific Shortcut workflow configuration — refer to the agent's Protected Status Policy as the source of truth. + +- **Name** (title): Follow the naming convention from the benchmark template +- **Description**: Structured using the benchmark epic description format, including: + - Business overview + - Business value statement + - Success metrics / criteria +- **Acceptance criteria**: Transferred from extracted tasks, formatted as markdown checklists +- **Labels**: Suggest relevant labels based on the epic's domain (do not hardcode project-specific values) + +**Step 3: Format each story for Shortcut** + +For each user story, create a Shortcut-ready story entry with: + +> **Protected Status Guard**: If a story has a protected workflow state (Done, Completed), preserve its content exactly as imported. Do not reformat, reword, or modify any fields. Mark it with `🔒` in the output and skip all formatting steps below for this story. Note: The full list of protected states should be confirmed with the user for their specific Shortcut workflow configuration — refer to the agent's Protected Status Policy as the source of truth. + +- **Name** (title): Follow the naming convention from the benchmark template +- **Story Type**: `feature`, `bug`, or `chore` +- **Description**: Structured using the benchmark story description format, including: + - Context paragraph linking to the parent epic + - User story in "As a… I want… So that…" format + - Requirements as a numbered list + - High-level technical notes (only if present in extracted tasks) +- **Acceptance criteria**: Formatted as a markdown checklist +- **Estimate guidance**: Include a sizing suggestion (e.g., Small / Medium / Large) based on scope complexity — but note this is a suggestion, not an estimate. The team should estimate during refinement. +- **Labels**: Consistent with the parent epic's labels plus any story-specific labels. Shortcut does not have a separate Priority field — if the team wants priority tracking, suggest using labels like `priority:critical`, `priority:high`, `priority:medium`, `priority:low`. +- **Parent epic**: Reference to the parent epic by name (will be linked by ID after creation) + +**Step 4: Validate completeness against benchmark** + +> **Protected Status Guard**: Skip completeness validation for tasks with a protected workflow state (Done, Completed) — their content is preserved as-is and is not subject to benchmark compliance. Refer to the agent's Protected Status Policy for the full list of protected states. + +Cross-check every formatted task against the benchmark template: +- Are all required fields populated? +- Do descriptions follow the expected structure? +- Are acceptance criteria written as verifiable conditions? +- Is the language business-oriented (not technical jargon)? +- Are labels consistent across related tasks? + +Create a summary table showing completeness status for each task. + +**Step 5: Flag uncertain fields and ask user** + +> **Protected Status Guard**: Do not flag or ask the user about fields on tasks with a protected workflow state (Done, Completed). These tasks are read-only and their fields cannot be changed. Refer to the agent's Protected Status Policy for the full list of protected states. + +For any task where: +- A required field could not be confidently filled from the source materials +- The story type is ambiguous +- The scope of a story is unclear +- Labels or categorisation is uncertain + +Use `askQuestions` to get user input. Ask exactly **one question per `askQuestions` call**, each scoped to a single epic or story. The question must identify which task has the uncertain field and what field is missing (e.g., "[Epic 2: Payment Processing > Story 2.1: User can checkout] The story type for this story could not be determined from the workshop materials. Should it be `feature` or `chore`?"). Do not proceed to the review gate until all flags are resolved. + +**Step 6: Formatting Review — User reviews formatted markdown** + +Present the formatted output to the user for review. If changes were made during formatting (e.g., rewording, label adjustments), present each changed task individually using one `askQuestions` call per task, identifying the specific epic/story and the change made. Ask: "Is this change acceptable?" + +After all individual changes are reviewed, ask one workflow-level question: "All formatting is complete. Are you happy with these tasks? Any final changes before I proceed to save and push?" + +The user must explicitly approve before proceeding. If changes are requested, update and re-present the affected tasks individually. + +**Step 7: Save the Shortcut-ready tasks document** + +Generate the final output following the `./shortcut-task.example.md` template format. + +Include the `Shortcut ID` field for every epic and story. For newly formatted tasks (not yet pushed to Shortcut), set the Shortcut ID to `—` as a placeholder. For tasks imported from Shortcut or previously pushed, preserve their existing Shortcut ID. + +Save the file to `specifications//formatted-tasks.md`. + +**Step 8: Push Approval — User approves Shortcut push** + +Before creating any stories in Shortcut, confirm with the user: +- Target Shortcut workspace and project/team +- Whether to create all tasks at once or in batches +- Any final adjustments + +This is the final gate — after this, stories will be created in Shortcut. + +**Step 9: Create or update stories in Shortcut** + +Before pushing, present a **sync summary** to the user: +- **(a)** Tasks to be **CREATED** (Shortcut ID is `—`) — list names and count +- **(b)** Tasks to be **UPDATED** (Shortcut ID is populated and workflow state is NOT protected) — list names, IDs, and count +- **(c)** Tasks **SKIPPED** (Shortcut ID is populated and workflow state is protected) — list names, IDs, workflow states, and count +- Get explicit user approval before proceeding. + +Using the Shortcut tools, process tasks based on their Shortcut ID: + +**For tasks without a Shortcut ID (create):** +1. Create all **epics** first (to get their Shortcut IDs) +2. After creating each epic, **immediately** update the corresponding entry in `formatted-tasks.md` with the returned Shortcut ID — do not wait until all tasks are created +3. Create all **stories** linked to their parent epics +4. After creating each story, **immediately** update `formatted-tasks.md` with its Shortcut ID +5. Add any **links** between stories (blocked-by, related-to relationships) + +**For tasks with an existing Shortcut ID (update):** +1. First, check the task's Workflow State field. If the workflow state is protected (refer to the agent's Protected Status Policy), **skip this task** — do not send any update to Shortcut. It was already counted in the sync summary under category (c). +2. Update the existing Shortcut story/epic with the local content +3. Fields to update: Name, Description, Labels, Estimate +4. Fields NOT to update: Story Type, Epic link (unless the user explicitly requests re-linking) +5. If an update fails because the story no longer exists in Shortcut, inform the user and offer to create a new story instead + +After all tasks are processed, report the final state back to the user — showing all Shortcut IDs in `formatted-tasks.md` and confirming which were created, updated, and skipped (with their workflow states). + +If any story creation or update fails, inform the user immediately and ask how to proceed. + +## Per-Change Modification Flow + +When the user requests a change to a specific task outside of the main formatting workflow (e.g., "add acceptance criteria to Story 2.3" or "change the labels of Epic 1"): + +0. **Check the task's Workflow State field**. If it is protected (refer to the agent's Protected Status Policy), inform the user that this task is protected and cannot be modified: _"This task has a protected workflow state ([state]). Per the Protected Status Policy, tasks with a protected workflow state cannot be modified. If this state is incorrect, please update it in Shortcut first, then re-import."_ Do not apply the change locally or in Shortcut. Stop here. +1. **Update the local `formatted-tasks.md` first** — apply the requested change to the file +2. **Ask the user**: "Do you want to push this change to Shortcut now?" (using one `askQuestions` call) +3. **If yes** — use the task's Shortcut ID to update the specific story/epic via Shortcut tools. If the task has no Shortcut ID (`—`), inform the user that the task has not been pushed yet and offer to create it +4. **If no** — the change remains local in `formatted-tasks.md` until the next batch push + +## Shortcut Markdown Note + +Shortcut uses standard Markdown natively. No markdown conversion is needed — the same markdown used in `formatted-tasks.md` is used when pushing to Shortcut. + +## Import Mode: Shortcut → Local + +This is an alternative entry point for the skill. Instead of formatting extracted tasks, the agent fetches existing Shortcut stories and converts them into the `formatted-tasks.md` format with Shortcut IDs pre-populated. This enables iterating on existing Shortcut backlogs using the agent's skills. + +### Import Process + +``` +Import progress: +- [ ] Step I-1: Identify import target +- [ ] Step I-2: Fetch stories from Shortcut +- [ ] Step I-3: Map Shortcut fields to benchmark template +- [ ] Step I-4: Generate formatted-tasks.md +- [ ] Step I-5: Present imported tasks for user review +- [ ] Step I-6: Save to specifications directory +``` + +**Step I-1: Identify import target** + +Ask the user to specify what to import. Accept any of these: +- A **Shortcut project or team name** — imports all epics and their linked stories +- **Specific epic IDs** — imports those epics and their child stories +- **Search terms or filters** — imports stories matching the search criteria + +Use one `askQuestions` call to determine the import scope if the user hasn't specified it. + +**Step I-2: Fetch stories from Shortcut** + +Using the Shortcut tools: +1. Fetch the targeted epics and stories from Shortcut +2. For each epic, fetch its child stories (linked via epic reference) +3. Collect all fields: Name, Description, Story Type, Labels, Workflow State, Estimate, Shortcut ID, Epic link + +**Step I-3: Map Shortcut fields to benchmark template** + +Convert each fetched task into the benchmark template format: + +| Shortcut Field | Template Field | Notes | +|---|---|---| +| Name | Name | Direct mapping | +| Description | Description sections | Parse into structured sections (Overview/Value/Metrics for epics; Context/User Story/Requirements/Technical Notes for stories). If the Shortcut description does not follow a structured format, restructure it to match the template as closely as possible. | +| Story Type | Story Type | Direct mapping (feature/bug/chore) | +| Labels | Labels | Direct mapping | +| Shortcut ID | Shortcut ID | Populate directly | +| Epic link | Parent epic reference | Map to parent epic name | +| Estimate | Estimate / Sizing Guidance | If estimated, include; otherwise mark as TBD | +| Workflow State | Workflow State | Direct mapping of the Shortcut workflow state (e.g., Unstarted, In Progress, Done). Used to enforce the Protected Status Policy. | + +If an imported description cannot be cleanly restructured into the benchmark format, flag it for user review using one `askQuestions` call per flagged task. + +> **Protected Status Handling on Import**: After mapping all fields, check each imported task's Workflow State. If the workflow state is protected (refer to the agent's Protected Status Policy — by default Done and Completed, but confirm with the user for their specific Shortcut workflow configuration), mark the task as read-only by adding a `🔒` indicator next to its name. These tasks are imported for visibility but must never be modified locally or pushed back to Shortcut. Preserve their content exactly as fetched. + +**Step I-4: Generate formatted-tasks.md** + +Create the `formatted-tasks.md` file with all imported tasks in the benchmark template format. Every task must have its `Shortcut ID` field populated with the actual Shortcut ID. + +**Step I-5: Present imported tasks for user review** + +Present each imported task to the user for review using one `askQuestions` call per task. Highlight any descriptions that were restructured or fields that could not be mapped cleanly. Ask: "Does this imported task look correct?" + +**Step I-6: Save to specifications directory** + +Save the final file to `specifications//formatted-tasks.md`. + +After import, the user can modify the local file. For each change, the agent asks whether to push it to Shortcut immediately (using the Per-Change Modification Flow above). The user can also batch-push all local changes later using the standard push flow (Step 8 → Step 9). + +## Connected Skills + +- `tsh-task-extracting` - provides the extracted tasks used as input for formatting +- `tsh-using-shortcut` - provides guidelines for Shortcut API interactions used during push and import flows diff --git a/.github/skills/tsh-shortcut-task-formatting/shortcut-task.example.md b/.github/skills/tsh-shortcut-task-formatting/shortcut-task.example.md new file mode 100644 index 00000000..ee163570 --- /dev/null +++ b/.github/skills/tsh-shortcut-task-formatting/shortcut-task.example.md @@ -0,0 +1,309 @@ +# Shortcut Task Benchmark Template + +This document defines the expected structure and fields for Shortcut epics and stories created by the business analyst agent. + +--- + +## Epic Template + +### Fields + +| Field | Required | Description | +|---|---|---| +| Name | Yes | Short, descriptive title. Format: `: ` | +| Description | Yes | Structured description (standard markdown with ## headings) | +| Acceptance Criteria | Yes | Business-oriented verifiable conditions | +| Labels | No | Domain or feature area labels relevant to the project | +| Shortcut ID | No | Shortcut epic ID. Populated after creation or import. | +| Workflow State | No | Current Shortcut workflow state (e.g., Unstarted, In Progress, Done). Populated from Shortcut during import or after push. Used to enforce the Protected Status Policy — tasks with a protected workflow state are read-only. | + +### Description Format + +``` +## Overview + +<2-3 sentence description of what this epic delivers and why it matters> + +## Business Value + + + +## Success Metrics + +- +- +``` + +### Acceptance Criteria Format + +``` +- [ ] +- [ ] +- [ ] +``` + +--- + +## Story Template + +### Fields + +| Field | Required | Description | +|---|---|---| +| Name | Yes | Short, action-oriented title. Format: ` can ` | +| Story Type | Yes | `feature`, `bug`, or `chore` | +| Epic | Yes | Reference to parent Epic | +| Description | Yes | Structured description (standard markdown) | +| Acceptance Criteria | Yes | Checklist of verifiable conditions | +| Estimate | No | Team estimates during refinement. Agent provides sizing guidance: Small (1), Medium (2-3), Large (5+) | +| Labels | No | Inherited from epic + story-specific labels | +| Shortcut ID | No | Shortcut story ID. Populated after creation or import. | +| Workflow State | No | Current Shortcut workflow state (e.g., Unstarted, In Progress, Done). Populated from Shortcut during import or after push. Used to enforce the Protected Status Policy — tasks with a protected workflow state are read-only. | + +### Description Format + +``` +## Context + +This story is part of the [] epic. <1 sentence connecting this story to the epic's goal.> + +## User Story + +As a , I want so that . + +## Requirements + +1. +2. +3. + +## Technical Notes + + +``` + +### Acceptance Criteria Format + +``` +- [ ] +- [ ] +- [ ] +``` + +--- + +## Formatting Guidelines + +### General Rules + +- **Business language only**: Descriptions should be understandable by any stakeholder without technical knowledge +- **No implementation details**: Do not specify technologies, frameworks, or code patterns in stories — that is the architect's responsibility +- **Consistent tone**: Use active voice and present tense ("User can create…" not "User should be able to create…") +- **Verifiable acceptance criteria**: Every criterion must be testable with a clear pass/fail condition + +### Priority via Labels + +Shortcut does not have a separate Priority field in the same way as other project management tools. Instead, priority is conveyed through labels and story ordering within the backlog. If the team wants explicit priority tracking, use labels with a `priority:` prefix: + +| Workshop Priority | Shortcut Label | When to Use | +|---|---|---| +| Critical | `priority:critical` | Blocks all other work; must be done first | +| High | `priority:high` | Core functionality; needed for MVP | +| Medium | `priority:medium` | Important but not blocking; can follow MVP | +| Low | `priority:low` | Nice-to-have; can be deferred | + +### Labels + +Labels are project-specific. Suggest labels based on the epic's domain area, but do not hardcode values. Common patterns: +- Feature area: `auth`, `payments`, `dashboard`, `reporting` +- Type: `infrastructure`, `integration`, `ui`, `backend` +- Source: `workshop-` to track which workshop produced the task +- Priority: `priority:critical`, `priority:high`, `priority:medium`, `priority:low` + +### Handling Optional Fields + +- If a field cannot be filled from the available materials, mark it as `TBD - to be discussed during refinement` +- Do not invent information to fill optional fields +- Flag all `TBD` fields for user review + +### Shortcut ID Field + +The `Shortcut ID` field is empty (`—`) when the task has not yet been pushed to Shortcut. It is populated automatically after story creation or when importing existing Shortcut stories. When a Shortcut ID is present, the push flow will **update** the existing story instead of creating a new one. + +- Do not manually fill this field — it is managed by the agent +- After a successful push, the agent writes the Shortcut ID back into `formatted-tasks.md` +- After a successful import, the agent populates the Shortcut ID from the fetched stories + +### Workflow State Field + +The `Workflow State` field reflects the current Shortcut workflow state of the task (e.g., `Unstarted`, `Started`, `In Progress`, `Done`, `Completed`). It is empty (`—`) for tasks that have not been pushed to or imported from Shortcut. + +- Do not manually fill this field — it is managed by the agent +- After a successful import, the agent populates the Workflow State from the fetched Shortcut story +- After a successful push (create or update), the agent records the current workflow state returned by Shortcut +- Tasks whose workflow state is **Done** or **Completed** are considered **protected** by default and are treated as read-only. The agent will not modify their content locally or push updates to Shortcut for them. The full list of protected states should be confirmed with the user for their specific Shortcut workflow configuration — refer to the agent's Protected Status Policy for full details. + +--- + +## Example: Fully Populated Epic with Stories + +> **Note:** Description content is wrapped in code blocks in this document for structural clarity. When pushing to Shortcut, the content inside the code blocks is used as the description. + +### Epic: User Authentication: Secure Login and Account Access + +**Shortcut ID**: — +**Workflow State**: — + +**Description**: +``` +## Overview + +Enable users to securely log in, manage their accounts, and recover access if credentials are lost. This is the foundational epic that gates access to all application features. + +## Business Value + +Without authentication, the application cannot distinguish between users, enforce permissions, or protect user data. This epic enables personalised experiences and regulatory compliance (GDPR, SOC2). + +## Success Metrics + +- Users can register, log in, and access their personalised dashboard +- Password recovery flow resolves 95% of access issues without support intervention +- All authentication flows complete in under 3 seconds +``` + +**Acceptance Criteria**: + +- [ ] Users can create an account with email and password +- [ ] Users can log in with valid credentials +- [ ] Users receive an error message for invalid credentials +- [ ] Users can reset their password via email +- [ ] Session timeout redirects users to the login page + +**Labels**: `auth`, `priority:critical`, `workshop-2026-02-19` + +--- + +### Story 1.1: User can register a new account + +**Epic**: User Authentication: Secure Login and Account Access +**Story Type**: feature +**Shortcut ID**: 12345 +**Workflow State**: In Progress +**Sizing Guidance**: Medium (2-3) + +**Description**: +``` +## Context + +This story is part of the [User Authentication: Secure Login and Account Access] epic. It enables new users to create an account and gain access to the application. + +## User Story + +As a new user, I want to register an account with my email and password so that I can access the application's features. + +## Requirements + +1. Registration form collects email address and password +2. Email address must be unique across all accounts +3. Password must meet minimum security requirements (discussed: at least 8 characters) +4. User receives a confirmation email after registration +5. User is redirected to the dashboard after successful registration + +## Technical Notes + +Discussed during workshop: SSO integration may be added later as a separate story. For now, email/password registration only. +``` + +**Acceptance Criteria**: + +- [ ] Registration form is accessible from the landing page +- [ ] Duplicate email addresses are rejected with a clear error message +- [ ] Passwords shorter than 8 characters are rejected with guidance +- [ ] Confirmation email is sent within 1 minute of registration +- [ ] Successful registration redirects to user dashboard + +**Labels**: `auth`, `priority:critical`, `workshop-2026-02-19` + +--- + +### Story 1.2: User can log in with existing credentials + +**Epic**: User Authentication: Secure Login and Account Access +**Story Type**: feature +**Shortcut ID**: — +**Workflow State**: — +**Sizing Guidance**: Small (1) + +**Description**: +``` +## Context + +This story is part of the [User Authentication: Secure Login and Account Access] epic. It allows returning users to access their account. + +## User Story + +As a returning user, I want to log in with my email and password so that I can access my account and data. + +## Requirements + +1. Login form collects email and password +2. Valid credentials grant access to the user dashboard +3. Invalid credentials display a clear error message without revealing which field is wrong +4. Session is created with appropriate timeout + +## Technical Notes + +No specific technical considerations discussed. +``` + +**Acceptance Criteria**: + +- [ ] Login form is accessible from the landing page +- [ ] Valid credentials redirect to the user dashboard +- [ ] Invalid credentials show a generic error message +- [ ] Three consecutive failed attempts trigger a temporary lockout + +**Labels**: `auth`, `priority:critical`, `workshop-2026-02-19` + +--- + +### Story 1.3: User can reset forgotten password + +**Epic**: User Authentication: Secure Login and Account Access +**Story Type**: feature +**Shortcut ID**: 12347 +**Workflow State**: Unstarted +**Sizing Guidance**: Medium (2-3) + +**Description**: +``` +## Context + +This story is part of the [User Authentication: Secure Login and Account Access] epic. It provides a self-service recovery path for users who forget their password. + +## User Story + +As a user who forgot my password, I want to reset it via email so that I can regain access to my account without contacting support. + +## Requirements + +1. "Forgot password" link is visible on the login page +2. User enters their email to request a password reset +3. Reset link is sent to the registered email +4. Reset link expires after a defined period +5. User can set a new password via the reset link + +## Technical Notes + +Discussed during workshop: Reset link should expire after 24 hours. Team to confirm exact duration during refinement. +``` + +**Acceptance Criteria**: + +- [ ] "Forgot password" link is visible and accessible on the login page +- [ ] Password reset email is sent within 1 minute of request +- [ ] Reset link expires after the configured period +- [ ] Expired links show a clear message and option to request a new one +- [ ] New password must meet the same requirements as registration + +**Labels**: `auth`, `priority:high`, `workshop-2026-02-19` diff --git a/.github/skills/tsh-task-analysing/SKILL.md b/.github/skills/tsh-task-analysing/SKILL.md index 4508d0f3..6917ad96 100644 --- a/.github/skills/tsh-task-analysing/SKILL.md +++ b/.github/skills/tsh-task-analysing/SKILL.md @@ -25,7 +25,7 @@ Analysis progress: Before gathering information, determine how the task context was provided: - **Research & plan files exist** (`*.research.md`, `*.plan.md`): Read them as the primary source of requirements, acceptance criteria, scope, and definition of done. -- **Jira ID / task ID provided**: Use it to fetch task details from external tools (Step 1). +- **Task ID (Jira, Shortcut) provided**: Use it to fetch task details from external tools (Step 1). - **Context provided directly in the prompt**: When neither files nor a task ID are referenced, extract requirements, acceptance criteria, and scope from the user's message. Treat the prompt as the single source of truth. If critical information is missing, ask for clarification before proceeding. - **PDF files attached or referenced**: Use the `pdf-reader` tool to extract content from PDF documents before analyzing them. Treat the extracted content as a primary source alongside research files and Jira tasks. @@ -35,6 +35,7 @@ This determination affects how much of Steps 1–2 you need to execute — if th Check what tools are available. Look for common task and knowledge management tools like: - Atlassian Jira +- Shortcut - Atlassian Confluence - Notion - Linear diff --git a/.github/skills/tsh-task-extracting/SKILL.md b/.github/skills/tsh-task-extracting/SKILL.md index 980b9288..34a54cd6 100644 --- a/.github/skills/tsh-task-extracting/SKILL.md +++ b/.github/skills/tsh-task-extracting/SKILL.md @@ -5,7 +5,7 @@ description: Identify and structure epics and user stories from workshop materia # Task Extraction -This skill helps you identify discrete pieces of work (epics and user stories) from discovery workshop materials and structure them into a clear, business-oriented task breakdown. The output is intended for stakeholder review and eventual Jira creation — it is NOT a technical specification or implementation plan. +This skill helps you identify discrete pieces of work (epics and user stories) from discovery workshop materials and structure them into a clear, business-oriented task breakdown. The output is intended for stakeholder review and eventual task management tool creation — it is NOT a technical specification or implementation plan. ## What This Skill Produces @@ -113,7 +113,7 @@ After presenting all stories, ask one final workflow-level question: "Did I miss Iterate based on feedback until the user approves the task list. -This is **Review Gate 1** — the user must approve the task list before proceeding to Jira formatting. +This is **Review Gate 1** — the user must approve the task list before proceeding to task formatting. **Step 9: Save the extracted tasks document** diff --git a/.github/skills/tsh-task-quality-reviewing/SKILL.md b/.github/skills/tsh-task-quality-reviewing/SKILL.md index fe2951c1..2f37f74f 100644 --- a/.github/skills/tsh-task-quality-reviewing/SKILL.md +++ b/.github/skills/tsh-task-quality-reviewing/SKILL.md @@ -1,11 +1,11 @@ --- name: tsh-task-quality-reviewing -description: Analyze extracted epics and user stories for quality gaps, missing edge cases, and improvement opportunities. Runs domain-agnostic analysis passes, optionally enriches findings with Jira board context, and produces accept/reject suggestions that refine the task list before Jira formatting. +description: Analyze extracted epics and user stories for quality gaps, missing edge cases, and improvement opportunities. Runs domain-agnostic analysis passes, optionally enriches findings with existing task board context, and produces accept/reject suggestions that refine the task list before task formatting. --- # Task Quality Review -This skill performs a systematic quality analysis on an approved task list (epics and user stories) to identify gaps, missing edge cases, and improvement opportunities. It runs 10 domain-agnostic analysis passes, optionally enriches findings with existing Jira board context, and produces a structured list of suggestions the user can individually accept or reject. +This skill performs a systematic quality analysis on an approved task list (epics and user stories) to identify gaps, missing edge cases, and improvement opportunities. It runs 10 domain-agnostic analysis passes, optionally enriches findings with existing task board context, and produces a structured list of suggestions the user can individually accept or reject. The output is a **quality review report** documenting all suggestions, their dispositions, and any changes applied to the task list. @@ -23,7 +23,7 @@ The output is a **quality review report** documenting all suggestions, their dis - Does not estimate effort or change priorities - Does not invent domain-specific requirements without research backing - Does not modify tasks without explicit user approval -- Does not create, modify, or delete Jira issues (read-only access for enrichment) +- Does not create, modify, or delete issues in task management tools (read-only access for enrichment) ## Task Quality Review Process @@ -32,7 +32,7 @@ Use the checklist below and track your progress: ``` Quality review progress: - [ ] Step 1: Load inputs and establish context -- [ ] Step 2: Gather Jira board context (optional) +- [ ] Step 2: Gather task board context (optional) - [ ] Step 3: Build domain model from the task list - [ ] Step 4: Run analysis passes - [ ] Step 5: Enrich with domain research @@ -54,17 +54,17 @@ Collect and review all available materials: Build a complete picture of the project scope, actors, and features before proceeding to analysis. -**Step 2: Gather Jira board context (optional)** +**Step 2: Gather Task Management board context (optional)** -If Atlassian tools are available and the user has indicated a Jira project (either in their initial message or during the workflow): +If Task Management tools are available and the user has indicated a project (either in their initial message or during the workflow): -1. Check available Atlassian resources by calling `List accessible Resources`. +1. Check available resources using the appropriate tool interaction guidelines (`tsh-using-atlassian` or `tsh-using-shortcut`). 2. If multiple resources exist, ask the user which one to use. -3. If the user provided a Jira project key, use it. If not, ask once: "I have access to Jira. Would you like me to check an existing board for additional context? If so, what is the project key?" If the user declines, skip this step entirely. +3. If the user provided a Task Management project key, use it. If not, ask once: "I have access to Task Management tools. Would you like me to check an existing board for additional context? If so, what is the project key?" If the user declines, skip this step entirely. 4. Fetch existing epics and stories from the board. 5. Note: naming conventions, label usage, priority patterns, and any existing work that relates to the extracted tasks. -This enrichment is **entirely optional**. The skill works identically without Jira access. Do not block the review process if Jira is unavailable or the user declines. +This enrichment is **entirely optional**. The skill works identically without Task Management access. Do not block the review process if Task Management tools are unavailable or the user declines. **Step 3: Build domain model from the task list** @@ -260,7 +260,7 @@ Transform each finding from the analysis passes into a structured suggestion: 4. **Deduplicate**: If multiple passes produce findings that overlap, merge them into a single suggestion and note all contributing categories. -5. **Enrich with Jira context** (if available from Step 2): Cross-reference each suggestion with existing Jira issues. If a suggestion duplicates or overlaps with an existing issue, note the Jira issue key and adjust the suggestion (e.g., "This is already tracked as PROJ-123 — consider linking rather than creating a new story"). +5. **Enrich with task board context** (if available from Step 2): Cross-reference each suggestion with existing issues in the task management tool. If a suggestion duplicates or overlaps with an existing issue, note the issue key/ID and adjust the suggestion (e.g., "This is already tracked as [issue key/ID] — consider linking rather than creating a new story"). **Step 7: Present suggestions for user review** @@ -325,4 +325,5 @@ The report serves as an audit trail documenting: ## Connected Skills - `tsh-task-extracting` — provides the extracted tasks used as primary input for the quality review -- `tsh-jira-task-formatting` — consumes the updated task list after quality review suggestions are applied +- `tsh-jira-task-formatting` — consumes the updated task list after quality review when using Jira +- `tsh-shortcut-task-formatting` — consumes the updated task list after quality review when using Shortcut diff --git a/.github/skills/tsh-using-atlassian/SKILL.md b/.github/skills/tsh-using-atlassian/SKILL.md new file mode 100644 index 00000000..a08a6875 --- /dev/null +++ b/.github/skills/tsh-using-atlassian/SKILL.md @@ -0,0 +1,103 @@ +--- +name: tsh-using-atlassian +description: Guidelines for accessing Jira and Confluence via Atlassian MCP tools. Covers resource discovery, workspace selection, searching, reading, creating and updating issues and pages. +--- + +# Using Atlassian + +This skill provides guidelines for interacting with Jira and Confluence via Atlassian MCP tools. It covers resource discovery, workspace/project selection, and common operations. Any agent that needs to access Jira or Confluence should follow these guidelines. + +## Resource Discovery and Workspace Selection + +Before performing any Atlassian operation, determine which resource to use: + +1. **Check `vscode/memory`** for a stored Atlassian resource preference +2. **If found** → use the stored preference (confirm with the user only if they mention a different resource) +3. **If not found** → call `List accessible Resources` +4. **If single resource** → use it automatically +5. **If multiple resources** → ask the user via `vscode/askQuestions` which one to use +6. **Store selection** in `vscode/memory` for future calls in the same project + +Never skip resource discovery. Every Atlassian operation depends on having the correct workspace context. + +## Jira Operations + +### Searching Issues + +- **Rovo search** (`search` method) is the preferred search method — use it for natural language queries +- Use **JQL search** only when the user explicitly provides a JQL query or when precise filtering is needed (e.g., by status, assignee, sprint) +- Always include the project key or board context when searching to scope results + +### Reading Issue Details + +- Fetch issue details by issue key (e.g., `PROJ-123`) +- For epics with child stories, fetch the epic first, then fetch its children +- Extract and understand: Summary, Description, Status, Priority, Labels, Assignee, Sprint, Story Points, Linked Issues + +### Creating Issues + +Follow this sequence when creating issues: + +- **Create epics first** to obtain their Jira IDs +- Then create stories linked to parent epics using the parent ID +- After creating each issue, **immediately record the returned Jira Key** +- Required fields: Summary, Issue Type, Project Key +- Add Description, Priority, Labels, and Parent link as available +- Add relationships (blocked-by, related-to) **after both linked issues exist** + +### Updating Issues + +Before updating any issue: + +- **Check the issue's current status** against the Protected Status Policy (see below) +- If the status is protected, **do not update** — inform the caller +- **Fields safe to update**: Summary, Description, Priority, Labels, Acceptance Criteria +- **Fields NOT to update** unless explicitly requested: Issue Type, Parent link +- If an update fails because the issue no longer exists, report the error + +### Transitions and Status + +- Do **not** change issue status or transitions unless explicitly requested by the user +- If a status change is needed, verify available transitions for the issue first + +## Confluence Operations + +### Searching Pages + +- Use **Rovo search** for natural language queries across Confluence spaces +- Use **CQL** (Confluence Query Language) only when precise filtering is needed +- Scope searches to the relevant space when known + +### Reading Pages + +- Fetch page content by page ID or by searching for the page title +- Navigate page hierarchy when context requires understanding parent/child page relationships +- Extract and understand: Title, Body content, Labels, Space, Parent page + +### Creating and Updating Pages + +Creating and updating Confluence pages is supported but less common. Follow the same pattern: confirm the space, create with required fields, record the page ID. + +## Error Handling + +- If a resource is not accessible, inform the caller and suggest checking MCP server configuration +- If authentication fails, inform the caller — do not retry with different credentials +- If an operation fails, report the specific error and let the caller decide how to proceed +- Never silently skip failed operations + +## Protected Status Integration + +The agent using this skill defines the authoritative list of protected statuses — this skill defers to the agent's Protected Status Policy. + +Before any write operation on an existing issue: + +- **Check the issue's current status** against the agent's protected status list +- If protected → skip the operation and inform the caller with the status name +- Default protected statuses (as defined by the business analyst agent): **Done**, **Cancelled**, **PO APPROVE** + +If the agent does not define a Protected Status Policy, use the defaults above. + +## Connected Skills + +- `tsh-jira-task-formatting` — uses Atlassian tools to push formatted tasks to Jira +- `tsh-task-quality-reviewing` — may use Atlassian tools to check board context during quality review diff --git a/.github/skills/tsh-using-shortcut/SKILL.md b/.github/skills/tsh-using-shortcut/SKILL.md new file mode 100644 index 00000000..2abf1680 --- /dev/null +++ b/.github/skills/tsh-using-shortcut/SKILL.md @@ -0,0 +1,136 @@ +--- +name: tsh-using-shortcut +description: Guidelines for accessing Shortcut via Shortcut MCP tools. Covers resource discovery, workspace selection, searching, reading, creating and updating stories and epics. +--- + +# Using Shortcut + +This skill provides guidelines for interacting with Shortcut via `shortcut/*` MCP tools. It covers workspace context discovery, and common operations for stories, epics, iterations, and documents. Any agent that needs to access Shortcut should follow these guidelines. + +## Workspace Context Discovery + +Shortcut API tokens are scoped to a single workspace — there is no multi-workspace selection needed. Instead, establish context by identifying the current user and their teams: + +1. **Check `vscode/memory`** for stored Shortcut team preference for this project +2. **If found** → use the stored team (confirm with the user only if they mention a different team) +3. **If not found** → call `users-get-current` to identify the authenticated user, then `users-get-current-teams` to list their teams +4. **If single team** → use it automatically and store in `vscode/memory` +5. **If multiple teams** → ask the user via `vscode/askQuestions` which team to use +6. **Store selection** in `vscode/memory` for future calls in the same project + +Call `workflows-get-default` (with the selected team ID) early to cache the available workflow states and their IDs — these are needed for creating and transitioning stories. + +## Shortcut Operations + +### Searching Stories and Epics + +Use `stories-search` and `epics-search` with their filter parameters: + +- **By name**: `name` parameter (contains match) +- **By state**: `state` for epics (unstarted/started/done), `state` for stories (workflow state name), or boolean filters `isDone`, `isStarted`, `isUnstarted` +- **By owner**: `owner` parameter (use mention name or `"me"`) +- **By label**: `label` parameter (label name) +- **By epic**: `epic` parameter on `stories-search` (epic ID) — this is how to get all stories in an epic +- **By team**: `team` parameter (team name or mention) +- **By type**: `type` parameter on `stories-search` (feature/bug/chore) +- **By iteration**: use `iterations-get-stories` with the iteration ID +- **By date**: `created`, `updated`, `completed`, `due` parameters with date filter syntax (e.g., `today`, `2026-01-01..2026-03-01`, `*..*today`) + +Use `nextPageToken` from results to paginate through large result sets. + +To search on a specific project, use `projects-get-stories` with the project ID. + +### Reading Story and Epic Details + +- **Stories**: `stories-get-by-id` with `storyPublicId` (numeric). Use `full: true` for all fields. +- **Epics**: `epics-get-by-id` with `epicPublicId` (numeric). Use `full: true` for all fields. +- **Stories in an epic**: Use `stories-search` with `epic: ` — there is no direct "get stories by epic" method. +- **Key fields to extract**: Name, Description, Story Type (feature/bug/chore), Workflow State, Labels, Owners, Estimate, Epic, Iteration, Shortcut ID + +### Creating Stories and Epics + +**Create epics first** using `epics-create`: +- Required: `name` +- Optional: `description`, `owner`, `teamId` +- Record the returned epic ID immediately + +**Then create stories** using `stories-create`: +- Required: `name` AND either `team` or `workflow` (one of these must be provided) +- Optional: `description`, `epic` (link to parent), `type` (feature/bug/chore, defaults to feature), `iteration`, `owner` +- After each creation, **immediately record the returned Shortcut ID** + +**Add relationships** between stories using `stories-add-relation`: +- Supported types: `relates to`, `blocks`, `blocked by`, `duplicates`, `duplicated by` +- Both stories must exist before adding the relationship + +**Add subtasks** using `stories-create-subtask` (creates new) or `stories-add-subtask` (links existing story). + +### Updating Stories and Epics + +Before updating any item: + +- **Fetch the current item** using `stories-get-by-id` or `epics-get-by-id` +- **Check the workflow state** against the Protected Status Policy (see below) +- If protected, **do not update** — inform the caller + +**Stories** via `stories-update` (provide only fields to change): +- **Fields safe to update**: `name`, `description`, `labels`, `estimate`, `deadline`, `iteration`, `owner_ids` +- **Fields to update only when explicitly requested**: `type` (story type), `epic` (parent epic link), `workflow_state_id` (state change) +- **Custom fields**: Use `custom_fields` array with `field_id` and `value_id` — call `custom-fields-list` first to get available field IDs + +**Epics** via `epics-update` (provide only fields to change): +- **Fields safe to update**: `name`, `description`, `labels`, `deadline`, `owner_ids` + +### Workflow State Changes + +- Do **not** change workflow state unless explicitly requested by the user +- Workflow states are customizable per workflow — call `workflows-list` or `workflows-get-by-id` to get available states and their IDs +- To change a story's state, use `stories-update` with the `workflow_state_id` (numeric ID, not the state name) +- Epic states are simpler: use `epics-update` with `epic_state_id` or the deprecated `state` field (to do/in progress/done) + +### Labels + +- **List existing labels**: `labels-list` +- **Create new labels**: `labels-create` with `name` (and optional `color` hex, `description`) +- **Find stories by label**: `labels-get-stories` with `labelPublicId` + +### Iterations + +- **List iterations**: `iterations-search` or `iterations-get-active` / `iterations-get-upcoming` +- **Get stories in iteration**: `iterations-get-stories` with `iterationPublicId` +- **Create/update iterations**: `iterations-create` / `iterations-update` + +### Documents + +Shortcut has built-in document support (Markdown format): + +- **List documents**: `documents-list` +- **Search documents**: `documents-search` with `title` filter +- **Read document**: `documents-get-by-id` with `docId` +- **Create document**: `documents-create` with `title` and `content` (Markdown) +- **Update document**: `documents-update` with `docId` and updated `title` or `content` + +## Error Handling + +- If authentication fails, inform the caller — do not retry with different credentials +- If an operation fails, report the specific error and let the caller decide how to proceed +- Never silently skip failed operations +- If a story or epic no longer exists (e.g., deleted), report the error clearly + +## Protected Status Integration + +The agent using this skill defines the authoritative list of protected statuses — this skill defers to the agent's Protected Status Policy. + +Before any write operation on an existing item: + +- **Fetch the item first** to check its current workflow state +- **Compare against the agent's protected status list** +- If protected → skip the operation and inform the caller with the state name +- Default protected states: **Done**, **Completed** + +Shortcut workflows are customizable — the agent's Protected Status Policy determines the authoritative list. If the agent does not define a Protected Status Policy, use the defaults above. + +## Connected Skills + +- `tsh-shortcut-task-formatting` — uses Shortcut tools to push formatted tasks to Shortcut +- `tsh-task-quality-reviewing` — may use Shortcut tools to check board context during quality review diff --git a/.vscode/mcp.json b/.vscode/mcp.json index 23a011c4..4eab6c87 100644 --- a/.vscode/mcp.json +++ b/.vscode/mcp.json @@ -55,6 +55,16 @@ "command": "npx", "args": ["@sylphx/pdf-reader-mcp"], "type": "stdio" + }, + "shortcut": { + "command": "npx", + "args": [ + "-y", + "@shortcut/mcp@latest" + ], + "env": { + "SHORTCUT_API_TOKEN": "" + } } }, "inputs": [] diff --git a/README.md b/README.md index fbd0461d..4e72aed7 100644 --- a/README.md +++ b/README.md @@ -27,14 +27,14 @@ This repository supports the **full product development lifecycle** with AI-powe ### 🛠 Development – Architecture & Implementation -- 🧑‍💻 **Agents** – Engineering Manager, Context Engineer, Architect, Software Engineer. -- 💬 **Prompts** – `/tsh-implement` (internally delegates to Context Engineer for research and Architect for planning). +- 🧑‍💻 **Agents** – Context Engineer, Architect, Software Engineer. +- 💬 **Prompts** – `/tsh-research`, `/tsh-plan`, `/tsh-implement`. - 🧰 **Skills** – Architecture Design, Technical Context Discovery, Frontend Implementation, Implementation Gap Analysis, SQL & Database Engineering, Codebase Analysis. ### ✅ Quality – Review & Testing - 🧑‍💻 **Agents** – Code Reviewer, UI Reviewer, E2E Engineer. -- 💬 **Prompts** – `/tsh-review`, `/tsh-review-ui`, `/tsh-review-codebase`. +- 💬 **Prompts** – `/tsh-review`, `/tsh-review-ui`, `/tsh-review-codebase`, `/tsh-implement-e2e`. - 🧰 **Skills** – Code Review, UI Verification, E2E Testing. ### ⚙️ Copilot Customization – Extending the Toolchain @@ -50,7 +50,7 @@ This repository supports the **full product development lifecycle** with AI-powe --- -> **Why the `tsh-` prefix?** All artifacts in this repository use the `tsh-` prefix (e.g., `/tsh-implement`, `tsh-architect`) to avoid naming collisions with your own project-specific agents, skills, and prompts. You can safely use this alongside your own customizations without renaming anything. +> **Why the `tsh-` prefix?** All artifacts in this repository use the `tsh-` prefix (e.g., `/tsh-plan`, `tsh-architect`) to avoid naming collisions with your own project-specific agents, skills, and prompts. You can safely use this alongside your own customizations without renaming anything. --- @@ -86,12 +86,12 @@ We support the **full product development lifecycle**, organized into three phas - Keeps changes scoped to the task, respecting existing architecture. - For UI tasks: automatically includes iterative Figma verification to match designs. -**Single flow: Implement → Review** +**Single flow: Plan → Implement** | Step | Command | What happens | |---|---|---| -| Implement | `/tsh-implement` | Engineering Manager orchestrates the full cycle: research → plan → implementation. For UI tasks includes iterative Figma verification. | -| Review | `/tsh-review` | Structured code review against acceptance criteria, security, and reliability | +| Plan | `/tsh-plan` | Architecture & steps; for UI tasks includes component breakdown with Figma refs | +| Implement | `/tsh-implement` | Backend & frontend code; for UI tasks includes iterative Figma verification (via internal prompt) | ### Phase 3: ✅ Quality – Review & Testing @@ -111,21 +111,26 @@ We support the **full product development lifecycle**, organized into three phas ↳ ✅ Approve at each gate before proceeding 🛠 DEVELOPMENT -2️⃣ /tsh-implement - ↳ 🔍 Engineering Manager delegates to Context Engineer for research +2️⃣ /tsh-research ↳ 📖 Review the generated research document - ↳ ✅ Confirm to proceed to planning - ↳ 🧱 Engineering Manager delegates to Architect for planning + ↳ ✅ Verify accuracy, iterate if needed + +3️⃣ /tsh-plan ↳ 📖 Review the implementation plan ↳ ✅ Confirm scope, phases, and acceptance criteria - ↳ 💻 Engineering Manager delegates implementation to specialized agents + +4️⃣ /tsh-implement ↳ 📖 Review code changes after each phase ↳ ✅ Test functionality, verify against plan ✅ QUALITY -3️⃣ /tsh-review +5️⃣ /tsh-review ↳ 📖 Review findings and recommendations ↳ ✅ Address blockers before merging + +6️⃣ /tsh-implement-e2e + ↳ 📖 Review generated Page Objects, test files, and fixtures + ↳ ✅ Run tests locally, verify they pass ``` ### Example: Full Lifecycle (UI Flow with Figma) @@ -137,22 +142,27 @@ We support the **full product development lifecycle**, organized into three phas ↳ ✅ Approve at each gate before proceeding 🛠 DEVELOPMENT -2️⃣ /tsh-implement - ↳ 🔍 Engineering Manager delegates to Context Engineer for research +2️⃣ /tsh-research ↳ 📖 Review research doc – verify Figma links, requirements - ↳ ✅ Confirm to proceed to planning - ↳ 🧱 Engineering Manager delegates to Architect for planning + ↳ ✅ Iterate until context is complete and accurate + +3️⃣ /tsh-plan ↳ 📖 Review plan – check component breakdown, design references ↳ ✅ Confirm phases align with Figma structure - ↳ 💻 Engineering Manager delegates UI tasks to Software Engineer + +4️⃣ /tsh-implement ↳ 📖 Review code changes and UI Verification Summary ↳ ✅ Manually verify critical UI elements in browser - ↳ 🔄 Engineering Manager calls /tsh-review-ui in a loop until PASS or escalation + ↳ 🔄 Agent calls /tsh-review-ui in a loop until PASS or escalation ✅ QUALITY -3️⃣ /tsh-review +5️⃣ /tsh-review ↳ 📖 Review findings – code quality, a11y, performance ↳ ✅ Address all blockers before merging + +6️⃣ /tsh-implement-e2e + ↳ 📖 Review generated tests for the UI feature + ↳ ✅ Run tests locally, verify they pass ``` You can run any flow with either a **Jira ticket ID** or a **free-form task description**. @@ -435,12 +445,23 @@ All commands work with either a **Jira ID** or a **plain-text description**. ### 🛠 Development Commands +#### `/tsh-research ` + +- Gathers all available information about the task. +- Pulls context from Jira, design artifacts, and code (via MCPs where applicable). +- Outputs: task summary, assumptions, open questions, and suggested next steps. + +#### `/tsh-plan ` + +- Creates a **multi-step implementation plan**. +- Groups work into phases and tasks aligned with your repo structure. +- Outputs: checklist-style plan that can be executed by the Software Engineer agent. + #### `/tsh-implement ` -- Orchestrates the full development cycle: research → plan → implement. -- The Engineering Manager automatically delegates to Context Engineer (research) and Architect (planning) when needed, then to specialized agents for implementation. -- Asks for user confirmation between research, planning, and implementation phases. -- Outputs: research document, implementation plan, and concrete code modifications. +- Implements the previously defined plan. +- Proposes file changes, refactors, and new code in a focused way. +- Outputs: concrete modifications and guidance on how to apply/test them. ### ✅ Quality Commands @@ -468,6 +489,14 @@ All commands work with either a **Jira ID** or a **plain-text description**. - For monorepos, analyzes each layer/app separately using parallel subagents. - Outputs: prioritized `code-quality-report.md` with severity levels (🔴 Critical / 🟡 Important / 🟢 Nice to Have) and a recommended action plan. +#### `/tsh-implement-e2e ` + +- Creates comprehensive **end-to-end tests** for the feature using Playwright. +- Analyzes the application, designs test scenarios, and implements Page Objects. +- Uses **Playwright MCP** for real-time interaction and test verification. +- Follows BDD-style scenarios with proper Arrange-Act-Assert structure. +- Outputs: Page Objects, test files, fixtures, and execution report. + ### ⚙️ Copilot Customization Commands > To create or modify Copilot customization artifacts (agents, skills, prompts, instructions), use the `/create-custom-*` commands below. These route to the orchestrator which handles research, creation, and review automatically. @@ -633,7 +662,7 @@ To enable this, modify your `mcp.json` configuration (User or Workspace) to use ### What each MCP is used for -- 🧩 **Atlassian MCP** – access Jira issues for `/tsh-implement` and `/tsh-review` (and internally during research and planning phases). +- 🧩 **Atlassian MCP** – access Jira issues for `/tsh-research`, `/tsh-plan`, `/tsh-implement`, `/tsh-review`. - 🎨 **Figma MCP Server** – pull design details, components, and variables for design‑driven work. - 📚 **Context7 MCP** – semantic search in external docs and knowledge bases. - 🧪 **Playwright MCP** – run browser interactions and end‑to‑end style checks from Copilot. @@ -669,17 +698,9 @@ Once the repo is cloned and VS Code User Settings are configured: | Agent | Prompt | Purpose | |---|---|---| -| Engineering Manager | `/tsh-implement ` | Orchestrates research → plan → implementation by delegating to specialized agents | - -The Engineering Manager automatically delegates to: - -| Delegated Agent | Phase | Purpose | -|---|---|---| -| Context Engineer | Research (internal) | Gather context, identify gaps & risks | -| Architect | Planning (internal) | Create multi-step implementation plan | -| Software Engineer | Implementation | Backend, frontend, and UI implementation | -| DevOps Engineer | Implementation | Infrastructure, CI/CD, Kubernetes, Terraform | -| E2E Engineer | Implementation | End-to-end tests with Playwright | +| Context Engineer | `/tsh-research ` | Gather context, identify gaps & risks | +| Architect | `/tsh-plan ` | Create multi-step implementation plan | +| Software Engineer | `/tsh-implement ` | Backend, frontend, and UI implementation (UI tasks include iterative Figma verification) | ### ✅ Quality – Review & test @@ -687,6 +708,7 @@ The Engineering Manager automatically delegates to: |---|---|---| | Code Reviewer | `/tsh-review ` | Structured code review against criteria | | UI Reviewer | `/tsh-review-ui` | Single-pass UI vs Figma comparison | +| E2E Engineer | `/tsh-implement-e2e ` | End-to-end test creation with Playwright | | Architect | `/tsh-review-codebase` | Full codebase quality analysis | ### ⚙️ Copilot Customization – Extend the toolchain diff --git a/website/docs/agents/overview.md b/website/docs/agents/overview.md index 5d6a50be..46ac9d3e 100644 --- a/website/docs/agents/overview.md +++ b/website/docs/agents/overview.md @@ -16,35 +16,6 @@ Each agent has: - **Skill bindings** — Which skills it loads for domain-specific knowledge. - **Handoffs** — Buttons to seamlessly transition between workflow phases. -## Agent Handoff Diagram - -``` -┌──────────────────────┐ -│ Business Analyst │ -│ /tsh-analyze-materials│ -└──────┬───────────────┘ - │ Start Implementation - ▼ -┌─────────────────────────┐ -│ Engineering Manager │ ← Orchestrates the full cycle -│ /tsh-implement │ -└──────┬──────────────────┘ - │ Delegates to specialized agents - ├──────────────────┬──────────────────┬──────────────────┬──────────────────┬──────────────────┬──────────────────┐ - ▼ ▼ ▼ ▼ ▼ ▼ ▼ -┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ -│ Context │ │ Architect │ │ Software │ │ DevOps │ │ E2E │ │ Prompt │ │ UI Reviewer │ -│ Engineer │ │ (plan) │ │ Engineer │ │ Engineer │ │ Engineer │ │ Engineer │ │ /tsh-review- │ -│ (research) │ │ │ │ (app code) │ │ (infra) │ │ (tests) │ │ (prompts) │ │ ui │ -└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ - │ - ▼ -┌──────────────┐ -│ Code Reviewer │ -│ /tsh-review │ -└──────────────┘ -``` - ## Agent Summary ### 📋 Product Ideation Agents diff --git a/website/docs/getting-started/quick-wins.md b/website/docs/getting-started/quick-wins.md index a2cdb371..b3f7f902 100644 --- a/website/docs/getting-started/quick-wins.md +++ b/website/docs/getting-started/quick-wins.md @@ -51,17 +51,17 @@ This page shows how teams integrate Copilot Collections into their daily routine **With Copilot Collections:** ```text -/tsh-implement PROJ-101 +/tsh-research PROJ-101 ``` | Step | What Happens | |---|---| -| **1. Multi-source aggregation** | The Engineering Manager delegates to the Context Engineer, which pulls context from Jira, Confluence, Figma, and the codebase simultaneously via MCP integrations. | +| **1. Multi-source aggregation** | The Context Engineer agent pulls context from Jira, Confluence, Figma, and the codebase simultaneously via MCP integrations. | | **2. Contradiction detection** | The `tsh-task-analysing` skill cross-references requirements across sources and flags inconsistencies, missing details, and ambiguous language. | | **3. Open questions list** | The research document includes a structured list of open questions, assumptions that need validation, and risks — ready to send back to the PM. | -| **4. Scope validation** | The output highlights what’s covered by the ticket and what’s missing, so you can request clarification before writing a single line of code. | +| **4. Scope validation** | The output highlights what's covered by the ticket and what's missing, so you can request clarification before writing a single line of code. | -**Key prompts & agents:** `/tsh-implement` → Engineering Manager → Context Engineer +**Key prompts & agents:** `/tsh-research` → Context Engineer **Key skills:** `tsh-task-analysing`, `tsh-codebase-analysing` **Value:** Ambiguities are surfaced in minutes instead of days. The structured open questions list becomes a communication tool with PMs, reducing back-and-forth by 60–80%. @@ -79,16 +79,16 @@ This page shows how teams integrate Copilot Collections into their daily routine **With Copilot Collections:** ```text -/tsh-implement PROJ-456 +/tsh-research PROJ-456 ``` | Step | What Happens | |---|---| -| **1. Automatic context gathering** | The Engineering Manager delegates to the Context Engineer, which pulls requirements from Jira, related Confluence docs, and Figma designs via MCP integrations. | +| **1. Automatic context gathering** | The Context Engineer agent pulls requirements from Jira, related Confluence docs, and Figma designs via MCP integrations. | | **2. Codebase analysis** | The `tsh-codebase-analysing` skill traces dependencies, identifies business logic patterns, and maps the data flow across layers. | | **3. Structured output** | A `.research.md` document is generated with a task summary, identified components, assumptions, open questions, and risks. | -**Key prompts & agents:** `/tsh-implement` → Engineering Manager → Context Engineer The research document becomes a reusable artifact that helps the entire team — not just you. +**Key prompts & agents:** `/tsh-research` → Context Engineer The research document becomes a reusable artifact that helps the entire team — not just you. --- @@ -101,17 +101,19 @@ This page shows how teams integrate Copilot Collections into their daily routine **With Copilot Collections:** ```text -/tsh-implement PROJ-789 +/tsh-research PROJ-789 +# Review the research doc, then: +/tsh-plan PROJ-789 ``` | Step | What Happens | |---|---| -| **1. Research phase** | The Engineering Manager delegates to the Context Engineer, which gathers all context — existing architecture, related features, constraints from Jira and Confluence. | -| **2. Architecture design** | The Engineering Manager delegates to the Architect, which creates a phased implementation plan with CREATE/MODIFY/REUSE labels for every task. | +| **1. Research phase** | Context Engineer gathers all context — existing architecture, related features, constraints from Jira and Confluence. | +| **2. Architecture design** | The Architect agent creates a phased implementation plan with CREATE/MODIFY/REUSE labels for every task. | | **3. Gap analysis** | The `tsh-architecture-designing` skill evaluates security considerations, scalability, and identifies risks before a single line of code is written. | | **4. Database planning** | If the feature involves data changes, the `tsh-sql-and-database-understanding` skill provides schema design patterns, indexing strategies, and migration safety checks. | -**Key prompts & agents:** `/tsh-implement` → Engineering Manager → Context Engineer + Architect , reviewed, and agreed upon before implementation starts. Every task is clearly scoped with action labels (CREATE, MODIFY, REUSE), reducing mid-sprint surprises by 50–70%. +**Key prompts & agents:** `/tsh-research` → Context Engineer, `/tsh-plan` → Architect , reviewed, and agreed upon before implementation starts. Every task is clearly scoped with action labels (CREATE, MODIFY, REUSE), reducing mid-sprint surprises by 50–70%. --- @@ -150,7 +152,9 @@ This page shows how teams integrate Copilot Collections into their daily routine **With Copilot Collections:** ```text -/tsh-implement PROJ-555 +/tsh-research PROJ-555 +/tsh-plan PROJ-555 +/tsh-implement Add new tables and migrate existing data for PROJ-555 ``` | Step | What Happens | @@ -160,7 +164,7 @@ This page shows how teams integrate Copilot Collections into their daily routine | **3. Query optimization** | The `tsh-sql-and-database-understanding` skill enforces `EXPLAIN ANALYZE`, proper indexing, join optimization, and parameterized queries. | | **4. ORM integration** | Supports TypeORM, Prisma, Doctrine, Eloquent, Entity Framework, Hibernate, and GORM — generating idiomatic code for your stack. | -**Key prompts & agents:** `/tsh-implement` → Engineering Manager → Context Engineer + Architect + Software Engineer +**Key prompts & agents:** `/tsh-research` → Context Engineer, `/tsh-plan` → Architect, `/tsh-implement` → Software Engineer **Key skills:** `tsh-sql-and-database-understanding`, `tsh-architecture-designing`, `tsh-technical-context-discovering` **Value:** Database performance issues are reduced by 40–60%. Migrations are planned with rollback strategies from the start. N+1 queries and missing indexes are caught during implementation, not in production. @@ -257,16 +261,17 @@ This page shows how teams integrate Copilot Collections into their daily routine ```text /tsh-review-codebase # Then pick your first task: -/tsh-implement PROJ-001 +/tsh-research PROJ-001 +/tsh-plan PROJ-001 ``` | Step | What Happens | |---|---| | **1. Codebase health snapshot** | `/tsh-review-codebase` gives you an immediate understanding of the codebase — its structure, patterns, tech stack, and quality issues. | | **2. Convention discovery** | The `tsh-technical-context-discovering` skill identifies project conventions, coding standards, and established patterns — you learn how this team works. | -| **3. Guided first task** | `/tsh-implement` on your first ticket produces a structured research document and step-by-step implementation plan automatically, so you deliver with confidence. | +| **3. Guided first task** | `/tsh-research` and `/tsh-plan` on your first ticket produce a structured analysis and step-by-step implementation plan, so you deliver with confidence. | -**Key prompts & agents:** `/tsh-review-codebase` → Architect, `/tsh-implement` → Engineering Manager → Context Engineer + Architect +**Key prompts & agents:** `/tsh-review-codebase` → Architect, `/tsh-research` → Context Engineer, `/tsh-plan` → Architect **Key skills:** `tsh-technical-context-discovering`, `tsh-codebase-analysing`, `tsh-architecture-designing` **Value:** Onboarding time is reduced by 40–60%. New developers deliver their first meaningful PR days earlier. They absorb project conventions automatically instead of learning them through review feedback. diff --git a/website/docs/intro.md b/website/docs/intro.md index 2f1651e0..eef470e2 100644 --- a/website/docs/intro.md +++ b/website/docs/intro.md @@ -48,8 +48,8 @@ Most teams use AI for code completion. **Copilot Collections turns AI into an en | Problem | Solution | Time | |---|---|---| | Workshop notes sitting in notebooks | `/tsh-analyze-materials` — epics and stories in Jira | ~15 min | -| New developer struggling with context | `/tsh-implement PROJ-123` — Engineering Manager gathers research automatically | ~3 min | -| No implementation plan | `/tsh-implement PROJ-123` — Engineering Manager creates plan automatically | ~5 min | +| New developer struggling with context | `/tsh-research PROJ-123` — structured research doc | ~3 min | +| No implementation plan | `/tsh-plan PROJ-123` — phased architecture plan | ~5 min | | UI doesn't match Figma | `/tsh-implement` — automated Figma verification loop via internal UI prompt | ~20 min | | Inconsistent code reviews | `/tsh-review PROJ-123` — structured multi-dimensional review | ~5 min | | Flaky or missing E2E tests | `/tsh-implement` — Engineering Manager delegates to E2E Engineer | ~10 min | @@ -61,11 +61,13 @@ Most teams use AI for code completion. **Copilot Collections turns AI into an en Every task follows a structured lifecycle: -> **Ideate → Implement → Review** +> **Ideate → Research → Plan → Implement → Review** 1. **Ideate** — Convert workshop materials into Jira-ready epics and stories. -2. **Implement** — Engineering Manager orchestrates research, planning, and implementation with specialized agents. -3. **Review** — Verify against acceptance criteria, security, and quality standards. +2. **Research** — Gather context from Jira, Figma, and the codebase. +3. **Plan** — Create a step-by-step implementation plan. +4. **Implement** — Execute the plan with scoped, reviewable changes. +5. **Review** — Verify against acceptance criteria, security, and quality standards. Each phase produces a documented artifact that feeds the next, ensuring nothing is lost between steps. Think of it as a **relay race** — every handoff is a reviewed artifact. diff --git a/website/docs/prompts/overview.md b/website/docs/prompts/overview.md index 54e4a177..5949b430 100644 --- a/website/docs/prompts/overview.md +++ b/website/docs/prompts/overview.md @@ -5,7 +5,7 @@ title: Prompts Overview # Prompts Overview -Copilot Collections includes **12 public prompts** — slash commands that trigger specific workflow actions across the full product lifecycle. Prompts are stored in `.github/prompts/` and become available as `/command` shortcuts in VS Code chat. +Copilot Collections includes **14 public prompts** — slash commands that trigger specific workflow actions across the full product lifecycle. Prompts are stored in `.github/prompts/` and become available as `/command` shortcuts in VS Code chat. ## How Prompts Work @@ -16,7 +16,7 @@ Each prompt file defines: - **Description** — Shown in VS Code's command palette. - **Instructions** — Detailed workflow steps, required skills, and output format. -When you type `/tsh-implement`, `/tsh-review`, etc. in the VS Code chat, the corresponding prompt file is loaded and executed by the bound agent. +When you type `/tsh-research`, `/tsh-plan`, etc. in the VS Code chat, the corresponding prompt file is loaded and executed by the bound agent. ## Public Prompts @@ -32,7 +32,9 @@ These are the user-facing commands available in VS Code chat. | Command | Agent | Description | |---|---|---| -| [/tsh-implement](./public/implement) | Engineering Manager | Orchestrate the full cycle: research → plan → implementation | +| [/tsh-research](./public/research) | Context Engineer | Gather context and requirements for a task | +| [/tsh-plan](./public/plan) | Architect | Create a structured implementation plan | +| [/tsh-implement](./public/implement) | Engineering Manager | Orchestrate implementation by delegating to specialized agents | ### ✅ Quality Commands @@ -61,12 +63,10 @@ These are the user-facing commands available in VS Code chat. ## Delegation via /tsh-implement -When you run [`/tsh-implement`](./public/implement), the Engineering Manager automatically handles the full development cycle. It first gathers context and creates an implementation plan (if needed), then delegates tasks to specialized agents. You don’t need to invoke individual agents — the orchestration is handled for you. +When you run [`/tsh-implement`](./public/implement), the Engineering Manager automatically delegates tasks to specialized agents based on the implementation plan. You don't need to invoke individual agents — the orchestration is handled for you. -| Phase | Delegated To | +| Task Type | Delegated To | |---|---| -| Research (context gathering) | Context Engineer (via [internal research prompt](./internal/research)) | -| Planning (architecture) | Architect (via [internal plan prompt](./internal/plan)) | | Backend / general code | Software Engineer | | Frontend with Figma | Software Engineer (via [internal UI prompt](./internal/implement-ui)) | | E2E tests | E2E Engineer | @@ -78,7 +78,7 @@ When you run [`/tsh-implement`](./public/implement), the Engineering Manager aut All prompts accept either: -- A **Jira ticket ID**: `/tsh-implement PROJ-123` -- A **task description**: `/tsh-implement Add pagination to the user list API` +- A **Jira ticket ID**: `/tsh-research PROJ-123` +- A **task description**: `/tsh-research Add pagination to the user list API` The agent adapts its behavior based on the input type — pulling context from Jira/Confluence for ticket IDs, or working from the description and codebase for free-form text. diff --git a/website/docs/workflow/frontend-flow.md b/website/docs/workflow/frontend-flow.md index f713f0fd..bfb15a6c 100644 --- a/website/docs/workflow/frontend-flow.md +++ b/website/docs/workflow/frontend-flow.md @@ -10,19 +10,21 @@ For UI-heavy tasks with Figma designs, use the specialized frontend workflow. Th ## Command Sequence ```text -1️⃣ /tsh-implement - ↳ 🔍 Engineering Manager delegates to Context Engineer for research +1️⃣ /tsh-research ↳ 📖 Review research doc – verify Figma links, requirements - ↳ ✅ Confirm to proceed to planning - ↳ 🧱 Engineering Manager delegates to Architect for planning + ↳ ✅ Iterate until context is complete and accurate + +2️⃣ /tsh-plan ↳ 📖 Review plan – check component breakdown, design references ↳ ✅ Confirm phases align with Figma structure - ↳ 💻 Engineering Manager delegates UI tasks to Software Engineer + +3️⃣ /tsh-implement + ↳ 📖 Engineering Manager delegates UI tasks to Software Engineer ↳ 📖 Review code changes and UI Verification Summary ↳ ✅ Manually verify critical UI elements in browser ↳ 🔄 Engineering Manager calls /tsh-review-ui in a loop until PASS or escalation -2️⃣ /tsh-review +4️⃣ /tsh-review ↳ 📖 Review findings – code quality, a11y, performance ↳ ✅ Address all blockers before merging ``` diff --git a/website/docs/workflow/overview.md b/website/docs/workflow/overview.md index 1309003a..4ed3989e 100644 --- a/website/docs/workflow/overview.md +++ b/website/docs/workflow/overview.md @@ -5,17 +5,17 @@ title: Workflow Overview # Workflow Overview -Copilot Collections is an AI product engineering framework that covers the **full product lifecycle** through a structured workflow: +Copilot Collections is an AI product engineering framework that covers the **full product lifecycle** through a structured 5-phase workflow: -> **Ideate → Implement → Review** +> **Ideate → Research → Plan → Implement → Review** -The Implement phase internally handles research and planning automatically. Each phase is executed by a specialized agent and produces documented artifacts. This ensures consistent, high-quality outputs across teams — from workshop materials all the way to production-ready, reviewed code. +Each phase is executed by a specialized agent and produces a documented artifact that feeds the next phase. This ensures consistent, high-quality outputs across teams — from workshop materials all the way to production-ready, reviewed code. :::tip The Relay Race Metaphor -Think of this workflow as a **relay race**. Each phase produces a deliverable — the "baton" — that is reviewed by the human and then passed to the next phase. Workshop materials feed the backlog, the Engineering Manager orchestrates research, planning, and implementation as a single flow, and the implementation feeds the review. Nothing is lost between steps, and every handoff is a documented artifact. +Think of this workflow as a **relay race**. Each phase produces a deliverable — the "baton" — that is reviewed by the human and then passed to the next phase. Workshop materials feed the backlog, the research document feeds the plan, the plan feeds the implementation, and the implementation feeds the review. Nothing is lost between steps, and every handoff is a documented artifact. ::: -## The Phases +## The 5 Phases ### 1. Ideate @@ -25,7 +25,23 @@ Think of this workflow as a **relay race**. Each phase produces a deliverable - Runs 10-pass quality review with three mandatory human review gates. - **Produces:** Jira-ready epics and stories with acceptance criteria, dependencies, and priorities. -### 2. Implement +### 2. Research + +- **Agent:** Context Engineer +- **Command:** `/tsh-research ` +- Builds context around a task using Jira, Figma, and other integrated tools. +- Identifies missing information, risks, and open questions. +- **Produces:** Research document (`.research.md`) with task summary, assumptions, open questions, and suggested next steps. + +### 3. Plan + +- **Agent:** Architect +- **Command:** `/tsh-plan ` +- Translates the task into a structured implementation plan. +- Breaks work into phases and executable steps. +- **Produces:** Implementation plan (`.plan.md`) with checklist-style phases, acceptance criteria, and technical constraints. + +### 4. Implement - **Agent:** Engineering Manager (orchestrates specialized agents) - **Command:** `/tsh-implement ` @@ -34,9 +50,9 @@ Think of this workflow as a **relay race**. Each phase produces a deliverable 2. **Plan** — Delegates to Architect to create a structured implementation plan. Asks for user confirmation before proceeding. 3. **Implement** — Delegates to Software Engineer, Prompt Engineer, DevOps Engineer, or E2E Engineer based on task type. - Tracks progress, runs quality checks after each task, and auto-triggers code review. -- **Produces:** Research document, implementation plan, and concrete code modifications. +- **Produces:** Concrete code modifications scoped to the task, applied by delegated agents. -### 3. Review +### 5. Review - **Agent:** Code Reviewer - **Command:** `/tsh-review ` @@ -60,6 +76,6 @@ Each step requires your review and verification. Open the generated documents, g The full lifecycle has specialized variants for different task types: - **[Workshop Analysis Flow](./workshop-flow)** — Convert discovery workshop materials into Jira-ready epics and stories using `/tsh-analyze-materials`. -- **[Standard Flow](./standard-flow)** — Backend/fullstack tasks using `/tsh-implement` → `/tsh-review` (research and planning happen internally). +- **[Standard Flow](./standard-flow)** — Backend/fullstack tasks using `/tsh-research` → `/tsh-plan` → `/tsh-implement` → `/tsh-review`. - **[Frontend Flow](./frontend-flow)** — UI tasks with Figma verification using `/tsh-implement` (which internally uses `/tsh-implement-ui`) and `/tsh-review-ui`. - **[E2E Testing Flow](./e2e-flow)** — End-to-end test creation delegated by the Engineering Manager to the E2E Engineer via `/tsh-implement`. From babbfe697bf9ba42cac94d70924251bb39eaf389 Mon Sep 17 00:00:00 2001 From: Adam Polak Date: Wed, 25 Mar 2026 21:14:03 +0100 Subject: [PATCH 2/4] fix: removed atlassian mention in EM agent --- .github/agents/tsh-engineering-manager.agent.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/agents/tsh-engineering-manager.agent.md b/.github/agents/tsh-engineering-manager.agent.md index 8a88841a..54b9683e 100644 --- a/.github/agents/tsh-engineering-manager.agent.md +++ b/.github/agents/tsh-engineering-manager.agent.md @@ -39,7 +39,7 @@ IF the task is missing both the necessary information and the implementation pla When you change between research, planning and implementation phases, make sure to wait for user confirmation before proceeding to the next phase. Use `vscode/askQuestions` tool to ask the user if they want to proceed with the next phase after research and planning phases. -Make sure to understand where the task is stored as it can be stored in Jira, Confluence or in the repository as a markdown file. Use `Atlassian` tool to access Jira and Confluence when needed. +Make sure to understand where the task is stored as it can be stored in Task Management tool, or in the repository as a markdown file. Use `tsh-knowledge` agent to access Task Management systems and knowledge base. Before delegating tasks, you review the implementation plan and feature context to understand the requirements and technical designs. You identify the specific tasks that need to be implemented and determine which specialized agents are best suited for each task based on their expertise and capabilities. From ea5922826b900229512e6546455f93b7ef5641e2 Mon Sep 17 00:00:00 2001 From: Adam Polak Date: Sun, 29 Mar 2026 23:04:04 +0200 Subject: [PATCH 3/4] feat: refactored skills --- website/docs/agents/business-analyst.md | 26 ++++--- website/docs/agents/knowledge.md | 67 +++++++++++++++++ website/docs/agents/overview.md | 5 +- website/docs/for-ctos.md | 2 +- website/docs/getting-started/mcp-setup.md | 7 +- website/docs/getting-started/quick-wins.md | 61 ++++++++-------- website/docs/integrations/overview.md | 5 +- website/docs/intro.md | 25 +++---- website/docs/prompts/overview.md | 25 ++++--- .../docs/prompts/public/analyze-materials.md | 23 +++--- website/docs/skills/overview.md | 72 ++++++++++--------- ...-task-formatting.md => task-formatting.md} | 65 +++++++++-------- website/docs/skills/task-quality-review.md | 2 +- ...ing-task-and-knowledge-management-tools.md | 49 +++++++++++++ website/docs/use-cases.md | 12 ++-- website/docs/workflow/frontend-flow.md | 15 ++-- website/docs/workflow/overview.md | 42 ++++------- website/docs/workflow/standard-flow.md | 2 +- website/docs/workflow/workshop-flow.md | 20 +++--- website/src/components/SdlcDiagram/index.tsx | 22 +++++- 20 files changed, 346 insertions(+), 201 deletions(-) create mode 100644 website/docs/agents/knowledge.md rename website/docs/skills/{jira-task-formatting.md => task-formatting.md} (50%) create mode 100644 website/docs/skills/using-task-and-knowledge-management-tools.md diff --git a/website/docs/agents/business-analyst.md b/website/docs/agents/business-analyst.md index 72012c79..16b35797 100644 --- a/website/docs/agents/business-analyst.md +++ b/website/docs/agents/business-analyst.md @@ -7,7 +7,7 @@ title: Business Analyst **File:** `.github/agents/tsh-business-analyst.agent.md` -The Business Analyst agent specializes in converting discovery workshop materials (transcripts, Figma designs, codebase context) into structured, Jira-ready epics and user stories. It can also import and iterate on existing Jira backlogs. +The Business Analyst agent specializes in converting discovery workshop materials (transcripts, Figma designs, codebase context) into structured epics and user stories ready for task management tools (Jira or Shortcut). It can also import and iterate on existing backlogs. ## Responsibilities @@ -15,9 +15,10 @@ The Business Analyst agent specializes in converting discovery workshop material - Analyzing Figma/FigJam designs for functional requirements and user flows. - Extracting epics and user stories from all processed materials. - Running quality review passes to identify gaps and missing edge cases. -- Formatting tasks for Jira using a benchmark template. -- Managing a three-gate review process before pushing to Jira. -- Importing existing Jira backlogs for local iteration and improvement. +- Formatting tasks for the target task management tool (Jira or Shortcut) using a benchmark template. +- Managing a three-gate review process before pushing to the task management tool. +- Importing existing backlogs from Jira or Shortcut for local iteration and improvement. +- Delegating all task management and knowledge base operations to the [Knowledge](./knowledge) agent. ## What It Produces @@ -26,7 +27,7 @@ A set of markdown files placed in `specifications//`: - **`cleaned-transcript.md`** — Cleaned and structured transcript with discussion topics, key decisions, action items, and open questions. - **`extracted-tasks.md`** — Extracted epics and user stories with acceptance criteria and dependencies. - **`quality-review.md`** — Quality review report with all suggestions and dispositions. -- **`jira-tasks.md`** — Final Jira-ready tasks formatted per the benchmark template. +- **`formatted-tasks.md`** — Final tasks formatted per the benchmark template for the target task management tool. ## What It Does NOT Do @@ -37,32 +38,37 @@ A set of markdown files placed in `specifications//`: ## Three-Gate Review Process -The Business Analyst enforces a strict review process — no data is pushed to Jira without explicit user approval: +The Business Analyst enforces a strict review process — no data is pushed to the task management tool without explicit user approval: | Gate | When | What | |---|---|---| | **Gate 1** | After task extraction | User reviews the epic/story breakdown | | **Gate 1.5** | After quality review | User accepts or rejects individual improvement suggestions | -| **Gate 2** | After Jira formatting | User reviews final formatted tasks before Jira push | +| **Gate 2** | After task formatting | User reviews final formatted tasks before push | ## Tool Access | Tool | Usage | |---|---| -| **Atlassian** | Create/update Jira issues, fetch existing backlogs, link stories to epics | | **Figma** | Analyze workshop designs, wireframes, and FigJam boards for functional requirements | | **PDF Reader** | Read and extract content from PDF workshop materials | | **Sequential Thinking** | Analyze complex discussions, resolve conflicts between materials, plan task structure | | **File Read/Edit/Search** | Read, modify, and search workspace files | -| **Sub-agents** | Delegate subtasks to specialized agents | +| **Sub-agents** | Delegate subtasks to specialized agents (including [Knowledge](./knowledge) for task management operations) | | **Todo** | Track task progress with structured checklists | +| **Ask Questions** | Clarify requirements and preferences with the user | + +:::note +The Business Analyst does **not** have direct access to task management tools (Jira, Shortcut) or knowledge bases (Confluence). All operations on these external systems are delegated to the [Knowledge](./knowledge) agent. +::: ## Skills Loaded - `tsh-transcript-processing` — Clean raw transcripts, structure by topics, extract decisions and action items. - `tsh-task-extracting` — Identify epics and user stories from all processed materials. - `tsh-task-quality-reviewing` — Run analysis passes to find gaps, edge cases, and improvements. -- `tsh-jira-task-formatting` — Format tasks for Jira, manage review gates, handle import mode. +- `tsh-task-formatting` — Format tasks for the target tool (Jira or Shortcut), manage review gates, handle import mode. +- `tsh-using-task-and-knowledge-management-tools` — Guidelines for interacting with task management and knowledge base tools. - `tsh-codebase-analysing` — Understand existing system context when relevant to task scope. ## Handoffs diff --git a/website/docs/agents/knowledge.md b/website/docs/agents/knowledge.md new file mode 100644 index 00000000..127c2c3f --- /dev/null +++ b/website/docs/agents/knowledge.md @@ -0,0 +1,67 @@ +--- +sidebar_position: 3 +title: Knowledge +--- + +# Knowledge Agent + +**File:** `.github/agents/tsh-knowledge.agent.md` + +The Knowledge agent specializes in using task management and knowledge base tools to provide task details and knowledge insights. It acts as the single gateway to external task management systems (Jira, Shortcut) and knowledge bases (Confluence), ensuring that all operations on these systems are performed securely and with proper context. + +## Responsibilities + +- Providing task details from Jira or Shortcut based on project context. +- Retrieving knowledge and documentation from Confluence. +- Creating and updating issues in task management tools on behalf of other agents (e.g., Business Analyst). +- Remembering tool preferences per workspace using VS Code memory. +- Detecting and selecting the correct workspace when multiple are available. + +## How It Determines Which Tool to Use + +The Knowledge agent follows a strict discovery process: + +1. **Check memory** — Look in VS Code memory for stored information about which tools the current project uses. +2. **Ask the user** — If no memory exists, ask the user about their task management and knowledge base preferences. +3. **Separate tool and knowledge base** — Never assume the same tool is used for both. A project may use Jira for tasks and Confluence for docs, or Shortcut for tasks with no knowledge base. + +## What It Does NOT Do + +- Does not process workshop materials or extract tasks (use the [Business Analyst](./business-analyst) for that). +- Does not produce implementation plans or architecture decisions. +- Does not suggest tools outside the supported list. + +## Tool Access + +| Tool | Usage | +|---|---| +| **Atlassian** | Access Jira for task management and Confluence for knowledge base | +| **Shortcut** | Access Shortcut for task management | +| **Sequential Thinking** | Decide which tool to use when the choice isn't obvious | +| **VS Code Memory** | Store and retrieve tool preferences per workspace | +| **Ask Questions** | Clarify user preferences and workspace selection | + +## Skills Loaded + +- `tsh-using-task-and-knowledge-management-tools` — Guidelines for interacting with supported task management and knowledge base tools. + +## Supported Tools + +### Task Management +- **Atlassian Jira** +- **Shortcut** + +### Knowledge Base +- **Atlassian Confluence** + +## How Other Agents Use It + +The Knowledge agent is primarily invoked as a sub-agent by other agents that need to interact with external task management or knowledge base systems: + +- **Business Analyst** — Delegates all task creation, updating, fetching, and backlog import operations. +- **Context Engineer** — Retrieves task details and related documentation for research. +- **Engineering Manager** — Fetches task context for implementation delegation. + +:::note +The Knowledge agent stores tool preferences in VS Code memory scoped to the current workspace. This means it remembers your project's preferred tools across sessions without asking repeatedly. +::: diff --git a/website/docs/agents/overview.md b/website/docs/agents/overview.md index 46ac9d3e..e8cf9a72 100644 --- a/website/docs/agents/overview.md +++ b/website/docs/agents/overview.md @@ -5,7 +5,7 @@ title: Agents Overview # Agents Overview -Copilot Collections provides **12 specialized agents** (plus 3 internal sub-agents) that together form an AI product engineering team covering the full delivery lifecycle — from product ideation through development, infrastructure, and quality assurance. Agents are stored in `.github/agents/` as `.agent.md` files. VS Code loads these automatically when the corresponding mode is selected. +Copilot Collections provides **13 specialized agents** (plus 3 internal sub-agents) that together form an AI product engineering team covering the full delivery lifecycle — from product ideation through development, infrastructure, and quality assurance. Agents are stored in `.github/agents/` as `.agent.md` files. VS Code loads these automatically when the corresponding mode is selected. ## How Agents Work @@ -22,7 +22,8 @@ Each agent has: | Agent | File | Role | Key Tools | |---|---|---|---| -| [Business Analyst](./business-analyst) | `tsh-business-analyst.agent.md` | Converts workshop materials into Jira-ready epics and stories | Atlassian, Figma, PDF Reader, Sequential Thinking | +| [Business Analyst](./business-analyst) | `tsh-business-analyst.agent.md` | Converts workshop materials into epics and stories for task management tools (Jira, Shortcut) | Figma, PDF Reader, Sequential Thinking | +| [Knowledge](./knowledge) | `tsh-knowledge.agent.md` | Provides task details and knowledge insights from task management and knowledge base tools | Atlassian, Shortcut, Sequential Thinking | ### 🛠 Development Agents diff --git a/website/docs/for-ctos.md b/website/docs/for-ctos.md index 9d375417..2205bfce 100644 --- a/website/docs/for-ctos.md +++ b/website/docs/for-ctos.md @@ -32,7 +32,7 @@ This isn't a prompt library. It's a framework that restructures **how work moves The framework covers three delivery phases: -**Product Ideation**: turning discovery workshops into structured, Jira-ready backlogs. Context gathering that used to take 30–60 minutes takes 3 minutes. Workshop transcripts become fully formed tickets with acceptance criteria, edge cases flagged, and backlog prioritised. +**Product Ideation**: turning discovery workshops into structured backlogs for Jira or Shortcut. Context gathering that used to take 30–60 minutes takes 3 minutes. Workshop transcripts become fully formed tickets with acceptance criteria, edge cases flagged, and backlog prioritised. **Development**: implementation guided by agents that understand your codebase, your Figma designs, and your Jira context simultaneously. The context-switching that fragments developer focus is replaced by a structured research-then-plan-then-implement loop. diff --git a/website/docs/getting-started/mcp-setup.md b/website/docs/getting-started/mcp-setup.md index cf5bbfda..fd6ffec7 100644 --- a/website/docs/getting-started/mcp-setup.md +++ b/website/docs/getting-started/mcp-setup.md @@ -5,7 +5,7 @@ title: MCP Setup # MCP Setup -To unlock the full workflow (Jira, Figma, code search, browser automation), you need to configure the MCP (Model Context Protocol) servers. Copilot Collections provides a ready-to-use template in `.vscode/mcp.json`. +To unlock the full workflow (Jira, Shortcut, Figma, code search, browser automation), you need to configure the MCP (Model Context Protocol) servers. Copilot Collections provides a ready-to-use template in `.vscode/mcp.json`. ## Installation Options @@ -66,7 +66,8 @@ Each MCP server enables specific capabilities within the workflow: | MCP Server | Purpose | Used By | |---|---|---| -| 🧩 **Atlassian** | Access Jira issues and Confluence pages for research, planning, implementation, and review | Business Analyst, Architect, Software Engineer, Code Reviewer | +| 🧩 **Atlassian** | Access Jira issues and Confluence pages for research, planning, implementation, and review | Knowledge, Architect, Software Engineer, Code Reviewer | +| 📌 **Shortcut** | Access Shortcut stories and projects for task management | Knowledge | | 🎨 **Figma MCP Server** | Pull design details, components, and variables for design-driven work | Software Engineer (UI), UI Reviewer | | 📚 **Context7** | Semantic search in external documentation and knowledge bases | All agents | | 🧪 **Playwright** | Run browser interactions and end-to-end style checks from Copilot | Software Engineer, E2E Engineer, UI Reviewer | @@ -115,6 +116,7 @@ Some MCP servers require additional setup: - **Atlassian** — Requires Atlassian account authentication. The HTTP MCP endpoint handles OAuth automatically via your browser. - **Figma** — Requires Figma account access. The HTTP MCP endpoint handles authentication via your browser. +- **Shortcut** — Requires a Shortcut API token. Set the `SHORTCUT_API_TOKEN` environment variable in the MCP configuration. - **Context7** — Works without an API key (with rate limits). Optional API key for higher limits. - **Playwright** — No authentication required. Runs locally via npx. - **Sequential Thinking** — No authentication required. Runs locally via npx. @@ -126,3 +128,4 @@ Some MCP servers require additional setup: - [Playwright MCP](https://github.com/microsoft/playwright-mcp) - [Figma MCP](https://help.figma.com/hc/en-us/articles/32132100833559-Guide-to-the-Figma-MCP-server) - [Sequential Thinking MCP](https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking) +- [Shortcut MCP](https://github.com/useshortcut/mcp) diff --git a/website/docs/getting-started/quick-wins.md b/website/docs/getting-started/quick-wins.md index b3f7f902..e48cb296 100644 --- a/website/docs/getting-started/quick-wins.md +++ b/website/docs/getting-started/quick-wins.md @@ -13,11 +13,11 @@ This page shows how teams integrate Copilot Collections into their daily routine ## Product Managers & Business Analysts -### 1. Converting Workshop Materials into a Jira Backlog +### 1. Converting Workshop Materials into a Structured Backlog -**When:** Your team just finished a discovery workshop. You have a raw transcript, Figma boards, and scattered notes — and you need to turn them into a structured, prioritized Jira backlog before the next sprint planning. +**When:** Your team just finished a discovery workshop. You have a raw transcript, Figma boards, and scattered notes — and you need to turn them into a structured, prioritized backlog before the next sprint planning. -**The old way:** Manually re-read the transcript, extract action items into a spreadsheet, copy-paste into Jira one by one, miss half the edge cases, and spend the next grooming session fixing vague stories. +**The old way:** Manually re-read the transcript, extract action items into a spreadsheet, copy-paste into your task management tool one by one, miss half the edge cases, and spend the next grooming session fixing vague stories. **With Copilot Collections:** @@ -33,12 +33,12 @@ This page shows how teams integrate Copilot Collections into their daily routine | **4. Gate 1 — Your review** | You review the extracted tasks. Split, merge, add, or remove stories until the breakdown matches what was discussed. | | **5. Quality review (10 passes)** | The `tsh-task-quality-reviewing` skill automatically runs 10 analysis passes — entity lifecycle completeness, error states, notification gaps, third-party boundaries, platform operations, and more. | | **6. Gate 1.5 — Accept/reject suggestions** | Each quality improvement is presented individually. You accept what makes sense and reject what doesn't apply. | -| **7. Jira formatting & push** | Tasks are formatted per the Jira benchmark template. After your final approval (Gate 2), epics and stories are created in Jira with proper linking. | +| **7. Task formatting & push** | Tasks are formatted per the benchmark template for the target tool. After your final approval (Gate 2), epics and stories are created in Jira or Shortcut with proper linking (via the Knowledge agent). | -**Key prompts & agents:** `/tsh-analyze-materials` → Business Analyst -**Key skills:** `tsh-transcript-processing`, `tsh-task-extracting`, `tsh-task-quality-reviewing`, `tsh-jira-task-formatting`, `tsh-codebase-analysing` +**Key prompts & agents:** `/tsh-analyze-materials` → Business Analyst (delegates to Knowledge for task management operations) +**Key skills:** `tsh-transcript-processing`, `tsh-task-extracting`, `tsh-task-quality-reviewing`, `tsh-task-formatting`, `tsh-codebase-analysing` -**Value:** A full discovery workshop is converted into a validated, Jira-ready backlog in a single session instead of days of manual work. The 10-pass quality review catches edge cases and gaps that manual extraction routinely misses — missing error states, notification gaps, incomplete entity lifecycles, and platform operations. The three-gate review process ensures nothing reaches Jira without your approval. +**Value:** A full discovery workshop is converted into a validated backlog in a single session instead of days of manual work. The 10-pass quality review catches edge cases and gaps that manual extraction routinely misses — missing error states, notification gaps, incomplete entity lifecycles, and platform operations. The three-gate review process ensures nothing reaches your task management tool without your approval. --- @@ -51,17 +51,17 @@ This page shows how teams integrate Copilot Collections into their daily routine **With Copilot Collections:** ```text -/tsh-research PROJ-101 +/tsh-implement PROJ-101 ``` | Step | What Happens | |---|---| -| **1. Multi-source aggregation** | The Context Engineer agent pulls context from Jira, Confluence, Figma, and the codebase simultaneously via MCP integrations. | +| **1. Automatic research** | As part of the internal research phase, the Context Engineer agent pulls context from Jira, Confluence, Figma, and the codebase simultaneously via MCP integrations. | | **2. Contradiction detection** | The `tsh-task-analysing` skill cross-references requirements across sources and flags inconsistencies, missing details, and ambiguous language. | | **3. Open questions list** | The research document includes a structured list of open questions, assumptions that need validation, and risks — ready to send back to the PM. | -| **4. Scope validation** | The output highlights what's covered by the ticket and what's missing, so you can request clarification before writing a single line of code. | +| **4. Scope validation** | The output highlights what's covered by the ticket and what's missing, so you can request clarification before proceeding to implementation. | -**Key prompts & agents:** `/tsh-research` → Context Engineer +**Key prompts & agents:** `/tsh-implement` → Engineering Manager → Context Engineer (research phase) **Key skills:** `tsh-task-analysing`, `tsh-codebase-analysing` **Value:** Ambiguities are surfaced in minutes instead of days. The structured open questions list becomes a communication tool with PMs, reducing back-and-forth by 60–80%. @@ -79,16 +79,19 @@ This page shows how teams integrate Copilot Collections into their daily routine **With Copilot Collections:** ```text -/tsh-research PROJ-456 +/tsh-implement PROJ-456 ``` | Step | What Happens | |---|---| -| **1. Automatic context gathering** | The Context Engineer agent pulls requirements from Jira, related Confluence docs, and Figma designs via MCP integrations. | +| **1. Automatic context gathering** | During the internal research phase, the Context Engineer agent pulls requirements from Jira, related Confluence docs, and Figma designs via MCP integrations. | | **2. Codebase analysis** | The `tsh-codebase-analysing` skill traces dependencies, identifies business logic patterns, and maps the data flow across layers. | | **3. Structured output** | A `.research.md` document is generated with a task summary, identified components, assumptions, open questions, and risks. | -**Key prompts & agents:** `/tsh-research` → Context Engineer The research document becomes a reusable artifact that helps the entire team — not just you. +**Key prompts & agents:** `/tsh-implement` → Engineering Manager → Context Engineer (research phase) +**Key skills:** `tsh-task-analysing`, `tsh-codebase-analysing` + +**Value:** The research document becomes a reusable artifact that helps the entire team — not just you. --- @@ -101,19 +104,20 @@ This page shows how teams integrate Copilot Collections into their daily routine **With Copilot Collections:** ```text -/tsh-research PROJ-789 -# Review the research doc, then: -/tsh-plan PROJ-789 +/tsh-implement PROJ-789 ``` | Step | What Happens | |---|---| -| **1. Research phase** | Context Engineer gathers all context — existing architecture, related features, constraints from Jira and Confluence. | -| **2. Architecture design** | The Architect agent creates a phased implementation plan with CREATE/MODIFY/REUSE labels for every task. | +| **1. Research phase** | The internal research phase gathers all context — existing architecture, related features, constraints from Jira and Confluence. | +| **2. Architecture design** | During the internal planning phase, the Architect agent creates a phased implementation plan with CREATE/MODIFY/REUSE labels for every task. | | **3. Gap analysis** | The `tsh-architecture-designing` skill evaluates security considerations, scalability, and identifies risks before a single line of code is written. | | **4. Database planning** | If the feature involves data changes, the `tsh-sql-and-database-understanding` skill provides schema design patterns, indexing strategies, and migration safety checks. | -**Key prompts & agents:** `/tsh-research` → Context Engineer, `/tsh-plan` → Architect , reviewed, and agreed upon before implementation starts. Every task is clearly scoped with action labels (CREATE, MODIFY, REUSE), reducing mid-sprint surprises by 50–70%. +**Key prompts & agents:** `/tsh-implement` → Engineering Manager → Context Engineer (research) → Architect (planning) +**Key skills:** `tsh-architecture-designing`, `tsh-sql-and-database-understanding`, `tsh-codebase-analysing` + +**Value:** Architecture decisions are documented, reviewed, and agreed upon before implementation starts. Every task is clearly scoped with action labels (CREATE, MODIFY, REUSE), reducing mid-sprint surprises by 50–70%. --- @@ -152,19 +156,17 @@ This page shows how teams integrate Copilot Collections into their daily routine **With Copilot Collections:** ```text -/tsh-research PROJ-555 -/tsh-plan PROJ-555 -/tsh-implement Add new tables and migrate existing data for PROJ-555 +/tsh-implement PROJ-555 ``` | Step | What Happens | |---|---| -| **1. Schema analysis** | The research phase identifies existing tables, relationships, and constraints affected by the change. | -| **2. Migration planning** | The Architect agent designs the migration with rollback strategies, following naming conventions and normalisation best practices. | +| **1. Schema analysis** | The internal research phase identifies existing tables, relationships, and constraints affected by the change. | +| **2. Migration planning** | During the internal planning phase, the Architect agent designs the migration with rollback strategies, following naming conventions and normalisation best practices. | | **3. Query optimization** | The `tsh-sql-and-database-understanding` skill enforces `EXPLAIN ANALYZE`, proper indexing, join optimization, and parameterized queries. | | **4. ORM integration** | Supports TypeORM, Prisma, Doctrine, Eloquent, Entity Framework, Hibernate, and GORM — generating idiomatic code for your stack. | -**Key prompts & agents:** `/tsh-research` → Context Engineer, `/tsh-plan` → Architect, `/tsh-implement` → Software Engineer +**Key prompts & agents:** `/tsh-implement` → Engineering Manager → Context Engineer (research) → Architect (planning) → Software Engineer (implementation) **Key skills:** `tsh-sql-and-database-understanding`, `tsh-architecture-designing`, `tsh-technical-context-discovering` **Value:** Database performance issues are reduced by 40–60%. Migrations are planned with rollback strategies from the start. N+1 queries and missing indexes are caught during implementation, not in production. @@ -261,17 +263,16 @@ This page shows how teams integrate Copilot Collections into their daily routine ```text /tsh-review-codebase # Then pick your first task: -/tsh-research PROJ-001 -/tsh-plan PROJ-001 +/tsh-implement PROJ-001 ``` | Step | What Happens | |---|---| | **1. Codebase health snapshot** | `/tsh-review-codebase` gives you an immediate understanding of the codebase — its structure, patterns, tech stack, and quality issues. | | **2. Convention discovery** | The `tsh-technical-context-discovering` skill identifies project conventions, coding standards, and established patterns — you learn how this team works. | -| **3. Guided first task** | `/tsh-research` and `/tsh-plan` on your first ticket produce a structured analysis and step-by-step implementation plan, so you deliver with confidence. | +| **3. Guided first task** | `/tsh-implement` on your first ticket performs automatic research and planning, then produces a step-by-step implementation — so you deliver with confidence. | -**Key prompts & agents:** `/tsh-review-codebase` → Architect, `/tsh-research` → Context Engineer, `/tsh-plan` → Architect +**Key prompts & agents:** `/tsh-review-codebase` → Architect, `/tsh-implement` → Engineering Manager → Context Engineer → Architect → Software Engineer **Key skills:** `tsh-technical-context-discovering`, `tsh-codebase-analysing`, `tsh-architecture-designing` **Value:** Onboarding time is reduced by 40–60%. New developers deliver their first meaningful PR days earlier. They absorb project conventions automatically instead of learning them through review feedback. diff --git a/website/docs/integrations/overview.md b/website/docs/integrations/overview.md index 52000063..648e0e21 100644 --- a/website/docs/integrations/overview.md +++ b/website/docs/integrations/overview.md @@ -5,7 +5,7 @@ title: Integrations Overview # Integrations Overview -Copilot Collections integrates with **11 external services** via the **Model Context Protocol (MCP)**. These integrations bring Jira, Figma, documentation, browser automation, structured reasoning, document reading, and cloud provider APIs directly into your Copilot sessions — enabling the end-to-end product engineering workflow. +Copilot Collections integrates with **12 external services** via the **Model Context Protocol (MCP)**. These integrations bring Jira, Shortcut, Figma, documentation, browser automation, structured reasoning, document reading, and cloud provider APIs directly into your Copilot sessions — enabling the end-to-end product engineering workflow. ## What is MCP? @@ -15,7 +15,8 @@ The Model Context Protocol allows VS Code Copilot agents to call external tools | Server | Type | Purpose | Used By | |---|---|---|---| -| [Atlassian](./atlassian) | HTTP | Jira & Confluence integration | BA, Architect, CR, CE, E2E, SE | +| [Atlassian](./atlassian) | HTTP | Jira & Confluence integration | Knowledge, Architect, CR, CE, E2E, SE | +| [Shortcut](https://github.com/useshortcut/mcp) | stdio | Shortcut task management integration | Knowledge | | [Figma](./figma) | HTTP | Design extraction and verification | BA, Architect, SE, UI Reviewer, CR, E2E | | [Context7](./context7) | stdio | Library documentation search | Architect, SE, CR, UI Reviewer, E2E, Copilot Eng., DevOps | | [Playwright](./playwright) | stdio | Browser automation and UI testing | SE, UI Reviewer, E2E | diff --git a/website/docs/intro.md b/website/docs/intro.md index eef470e2..2acd5232 100644 --- a/website/docs/intro.md +++ b/website/docs/intro.md @@ -20,17 +20,17 @@ Most teams use AI for code completion. **Copilot Collections turns AI into an en | Capability | Count | Description | |---|---|---| -| 🧑‍💻 **Specialized Agents** | 12 | Business Analyst, Context Engineer, Architect, Engineering Manager, Software Engineer, Prompt Engineer, Code Reviewer, UI Reviewer, E2E Engineer, DevOps Engineer, Copilot Engineer, Copilot Orchestrator | +| 🧑‍💻 **Specialized Agents** | 13 | Business Analyst, Knowledge, Context Engineer, Architect, Engineering Manager, Software Engineer, Prompt Engineer, Code Reviewer, UI Reviewer, E2E Engineer, DevOps Engineer, Copilot Engineer, Copilot Orchestrator | | 💬 **Public Prompts** | 12 | `/tsh-analyze-materials`, `/tsh-implement`, `/tsh-review`, `/tsh-review-ui`, `/tsh-review-codebase`, `/tsh-create-custom-agent`, `/tsh-create-custom-skill`, `/tsh-create-custom-prompt`, `/tsh-create-custom-instructions`, `/tsh-audit-infrastructure`, `/tsh-analyze-aws-costs`, `/tsh-analyze-gcp-costs` | -| 🔧 **Automatic Delegation** | via `/tsh-implement` | The Engineering Manager automatically routes tasks to Software Engineer, Prompt Engineer, E2E Engineer, DevOps Engineer, and UI Reviewer based on the implementation plan | -| 🧰 **Reusable Skills** | 31 | Transcript Processing, Task Extraction, Task Quality Review, Jira Task Formatting, Task Analysis, Architecture Design, Codebase Analysis, Code Review, Frontend Review, Implementation Gap Analysis, E2E Testing, Technical Context Discovery, Prompt Engineering, Frontend Implementation, Implementing Forms, Writing Hooks, Ensuring Accessibility, Optimizing Frontend, UI Verification, SQL & Database Engineering, CI/CD Implementation, Kubernetes Implementation, Terraform Modules, Observability Implementation, Secrets Management, Cloud Cost Optimization, Multi-Cloud Architecture Design, Creating Agents, Creating Skills, Creating Prompts, Creating Instructions | -| 🔌 **MCP Integrations** | 11 | Atlassian, Figma Dev Mode, Context7, Playwright, Sequential Thinking, PDF Reader, AWS API, AWS Documentation, GCP Gcloud, GCP Observability, GCP Storage | +| 🔧 **Automatic Delegation** | via `/tsh-implement` | The Engineering Manager automatically routes tasks to Software Engineer, Prompt Engineer, E2E Engineer, DevOps Engineer, Knowledge, and UI Reviewer based on the implementation plan | +| 🧰 **Reusable Skills** | 33 | Transcript Processing, Task Extraction, Task Quality Review, Task Formatting, Using Task & Knowledge Management Tools, Task Analysis, Architecture Design, Codebase Analysis, Code Review, Frontend Review, Implementation Gap Analysis, E2E Testing, Technical Context Discovery, Prompt Engineering, Frontend Implementation, Implementing Forms, Writing Hooks, Ensuring Accessibility, Optimizing Frontend, UI Verification, SQL & Database Engineering, CI/CD Implementation, Kubernetes Implementation, Terraform Modules, Observability Implementation, Secrets Management, Cloud Cost Optimization, Multi-Cloud Architecture Design, Creating Agents, Creating Skills, Creating Prompts, Creating Instructions | +| 🔌 **MCP Integrations** | 12 | Atlassian, Shortcut, Figma Dev Mode, Context7, Playwright, Sequential Thinking, PDF Reader, AWS API, AWS Documentation, GCP Gcloud, GCP Observability, GCP Storage | | 🧠 **Structured Workflows** | 5 | Standard Flow, UI Flow, E2E Testing Flow, Workshop Analysis Flow, Copilot Customization Flow | ## Key Benefits ### For Product Teams -- **Workshop to Jira in minutes** — Process transcripts, Figma designs, and documents into structured epics and stories with a quality review gate. No more lost workshop outputs. +- **Workshop to backlog in minutes** — Process transcripts, Figma designs, and documents into structured epics and stories with a quality review gate. Push to Jira or Shortcut. No more lost workshop outputs. - **Systematic backlog quality** — 10-pass quality analysis catches missing entity lifecycles, error states, notification gaps, and undocumented dependencies in both new and existing backlogs. ### For Developers @@ -47,9 +47,8 @@ Most teams use AI for code completion. **Copilot Collections turns AI into an en | Problem | Solution | Time | |---|---|---| -| Workshop notes sitting in notebooks | `/tsh-analyze-materials` — epics and stories in Jira | ~15 min | -| New developer struggling with context | `/tsh-research PROJ-123` — structured research doc | ~3 min | -| No implementation plan | `/tsh-plan PROJ-123` — phased architecture plan | ~5 min | +| Workshop notes sitting in notebooks | `/tsh-analyze-materials` — epics and stories in your task management tool | ~15 min | +| New task with vague requirements | `/tsh-implement PROJ-123` — automatic research, planning, and implementation | ~20 min | | UI doesn't match Figma | `/tsh-implement` — automated Figma verification loop via internal UI prompt | ~20 min | | Inconsistent code reviews | `/tsh-review PROJ-123` — structured multi-dimensional review | ~5 min | | Flaky or missing E2E tests | `/tsh-implement` — Engineering Manager delegates to E2E Engineer | ~10 min | @@ -61,13 +60,11 @@ Most teams use AI for code completion. **Copilot Collections turns AI into an en Every task follows a structured lifecycle: -> **Ideate → Research → Plan → Implement → Review** +> **Ideate → Implement → Review** -1. **Ideate** — Convert workshop materials into Jira-ready epics and stories. -2. **Research** — Gather context from Jira, Figma, and the codebase. -3. **Plan** — Create a step-by-step implementation plan. -4. **Implement** — Execute the plan with scoped, reviewable changes. -5. **Review** — Verify against acceptance criteria, security, and quality standards. +1. **Ideate** — Convert workshop materials into structured epics and stories for your task management tool. +2. **Implement** — A single `/tsh-implement` command triggers three internal phases: **Research** (gather context from Jira/Shortcut, Figma, and the codebase), **Plan** (create a step-by-step architecture plan), and **Build** (execute the plan with scoped, reviewable changes). +3. **Review** — Verify against acceptance criteria, security, and quality standards. Each phase produces a documented artifact that feeds the next, ensuring nothing is lost between steps. Think of it as a **relay race** — every handoff is a reviewed artifact. diff --git a/website/docs/prompts/overview.md b/website/docs/prompts/overview.md index 5949b430..23c6814e 100644 --- a/website/docs/prompts/overview.md +++ b/website/docs/prompts/overview.md @@ -5,7 +5,7 @@ title: Prompts Overview # Prompts Overview -Copilot Collections includes **14 public prompts** — slash commands that trigger specific workflow actions across the full product lifecycle. Prompts are stored in `.github/prompts/` and become available as `/command` shortcuts in VS Code chat. +Copilot Collections includes **12 public prompts** and **4 internal prompts** — slash commands that trigger specific workflow actions across the full product lifecycle. Prompts are stored in `.github/prompts/` and become available as `/command` shortcuts in VS Code chat. ## How Prompts Work @@ -16,7 +16,7 @@ Each prompt file defines: - **Description** — Shown in VS Code's command palette. - **Instructions** — Detailed workflow steps, required skills, and output format. -When you type `/tsh-research`, `/tsh-plan`, etc. in the VS Code chat, the corresponding prompt file is loaded and executed by the bound agent. +When you type `/tsh-implement`, `/tsh-review`, etc. in the VS Code chat, the corresponding prompt file is loaded and executed by the bound agent. ## Public Prompts @@ -26,15 +26,13 @@ These are the user-facing commands available in VS Code chat. | Command | Agent | Description | |---|---|---| -| [/tsh-analyze-materials](./public/analyze-materials) | Business Analyst | Process workshop materials into Jira-ready epics and stories | +| [/tsh-analyze-materials](./public/analyze-materials) | Business Analyst | Process workshop materials into epics and stories for Jira or Shortcut | ### 🛠 Development Commands | Command | Agent | Description | |---|---|---| -| [/tsh-research](./public/research) | Context Engineer | Gather context and requirements for a task | -| [/tsh-plan](./public/plan) | Architect | Create a structured implementation plan | -| [/tsh-implement](./public/implement) | Engineering Manager | Orchestrate implementation by delegating to specialized agents | +| [/tsh-implement](./public/implement) | Engineering Manager | Orchestrate full development cycle: research → plan → implement | ### ✅ Quality Commands @@ -61,6 +59,17 @@ These are the user-facing commands available in VS Code chat. | [/tsh-analyze-aws-costs](./public/analyze-aws-costs) | DevOps Engineer | AWS cost optimization and tagging compliance audit | | [/tsh-analyze-gcp-costs](./public/analyze-gcp-costs) | DevOps Engineer | GCP cost optimization and labeling compliance audit | +## Internal Prompts + +These prompts are not invoked directly by users. They are triggered automatically by `/tsh-implement` when the Engineering Manager delegates to specialized agents: + +| Prompt | Agent | Description | +|---|---|---| +| [/tsh-research](./internal/research) | Context Engineer | Gather context and requirements for a task | +| [/tsh-plan](./internal/plan) | Architect | Create a structured implementation plan | +| [/tsh-implement-ui](./internal/implement-ui) | Software Engineer + UI Reviewer | Implement UI components with Figma verification loop | +| [/tsh-engineer-prompt](./internal/engineer-prompt) | Prompt Engineer | Design and optimize LLM application prompts | + ## Delegation via /tsh-implement When you run [`/tsh-implement`](./public/implement), the Engineering Manager automatically delegates tasks to specialized agents based on the implementation plan. You don't need to invoke individual agents — the orchestration is handled for you. @@ -78,7 +87,7 @@ When you run [`/tsh-implement`](./public/implement), the Engineering Manager aut All prompts accept either: -- A **Jira ticket ID**: `/tsh-research PROJ-123` -- A **task description**: `/tsh-research Add pagination to the user list API` +- A **task ID**: `/tsh-implement PROJ-123` (Jira) or `/tsh-implement sc-12345` (Shortcut) +- A **task description**: `/tsh-implement Add pagination to the user list API` The agent adapts its behavior based on the input type — pulling context from Jira/Confluence for ticket IDs, or working from the description and codebase for free-form text. diff --git a/website/docs/prompts/public/analyze-materials.md b/website/docs/prompts/public/analyze-materials.md index efcc4c3c..f46cd6d1 100644 --- a/website/docs/prompts/public/analyze-materials.md +++ b/website/docs/prompts/public/analyze-materials.md @@ -8,12 +8,12 @@ title: /tsh-analyze-materials **Agent:** Business Analyst **File:** `.github/prompts/tsh-analyze-materials.prompt.md` -Processes discovery workshop materials and converts them into structured, Jira-ready epics and user stories. Can also import an existing Jira backlog for local iteration. +Processes discovery workshop materials and converts them into structured epics and user stories for your task management tool (Jira or Shortcut). Can also import an existing backlog for local iteration. ## Usage ```text -/tsh-analyze-materials +/tsh-analyze-materials ``` ## What It Does @@ -26,20 +26,21 @@ Processes discovery workshop materials and converts them into structured, Jira-r 4. **Gate 1 — Task Review** — Presents extracted tasks for user validation. Iterates until approved. 5. **Quality review** — Runs analysis passes against the approved task list to find gaps, missing edge cases, and improvements. 6. **Gate 1.5 — Suggestion Review** — Presents quality review suggestions individually for accept/reject. -7. **Format for Jira** — Applies the benchmark template to all tasks using the `tsh-jira-task-formatting` skill. -8. **Gate 2 — Push Approval** — Presents final formatted tasks for user review before Jira push. -9. **Push to Jira** — Creates epics and stories in Jira with proper linking. Reports created issue keys. +7. **Format for target tool** — Applies the benchmark template to all tasks using the `tsh-task-formatting` skill (delegates to Jira or Shortcut sub-skill). +8. **Gate 2 — Push Approval** — Presents final formatted tasks for user review before push. +9. **Push to task management tool** — Creates epics and stories with proper linking via the Knowledge agent. Reports created issue keys. -### Import Mode (Jira project key provided) +### Import Mode (project key or issue IDs provided) -When the user provides existing Jira issue keys or a project key instead of workshop materials, the agent skips transcript processing and task extraction. It fetches existing tasks from Jira, converts them into the local format, then proceeds to quality review and formatting. +When the user provides existing issue keys or a project key instead of workshop materials, the agent skips transcript processing and task extraction. It fetches existing tasks from the task management tool (via the Knowledge agent), converts them into the local format, then proceeds to quality review and formatting. ## Skills Loaded - `tsh-transcript-processing` — Clean and structure raw transcripts. - `tsh-task-extracting` — Identify epics and user stories from materials. - `tsh-task-quality-reviewing` — Analyze tasks for gaps and improvements. -- `tsh-jira-task-formatting` — Format tasks for Jira and manage push. +- `tsh-task-formatting` — Format tasks for the target tool and manage push. +- `tsh-using-task-and-knowledge-management-tools` — Guidelines for interacting with task management tools. - `tsh-codebase-analysing` — Understand existing codebase when relevant. ## Output @@ -52,7 +53,7 @@ specifications/ cleaned-transcript.md ← structured transcript extracted-tasks.md ← epics and stories (updated after quality review) quality-review.md ← quality review report - jira-tasks.md ← final Jira-ready tasks + formatted-tasks.md ← final formatted tasks for target tool ``` ## Input Flexibility @@ -64,9 +65,9 @@ The command accepts various input types: | Raw transcript text | Runs full workflow starting from transcript processing | | Structured notes | Skips transcript processing, starts from task extraction | | Figma links | Analyzes designs for functional requirements | -| Jira project key | Imports existing backlog for local iteration | +| Project key or issue IDs | Imports existing backlog for local iteration | | Combination | Processes all available materials together | :::tip -The three review gates are mandatory. No data is pushed to Jira without your explicit approval at each gate. Review each output carefully — the agent produces business-oriented tasks that stakeholders should be able to understand without technical knowledge. +The three review gates are mandatory. No data is pushed to your task management tool without your explicit approval at each gate. Review each output carefully — the agent produces business-oriented tasks that stakeholders should be able to understand without technical knowledge. ::: diff --git a/website/docs/skills/overview.md b/website/docs/skills/overview.md index d32f17b6..22e2b63d 100644 --- a/website/docs/skills/overview.md +++ b/website/docs/skills/overview.md @@ -5,7 +5,7 @@ title: Skills Overview # Skills Overview -Copilot Collections includes **31 reusable skills** — knowledge modules that provide specialized domain expertise, structured processes, and quality templates. They encode tested best practices for every phase of the product lifecycle. Skills are stored in `.github/skills/` and loaded automatically by agents when their domain applies to the current task. +Copilot Collections includes **33 reusable skills** — knowledge modules that provide specialized domain expertise, structured processes, and quality templates. They encode tested best practices for every phase of the product lifecycle. Skills are stored in `.github/skills/` and loaded automatically by agents when their domain applies to the current task. ## How Skills Work @@ -27,7 +27,8 @@ When an agent starts a task, it checks all available skills and decides which on | [tsh-transcript-processing](./transcript-processing) | Workshop transcript cleaning and structuring | Business Analyst | | [tsh-task-extracting](./task-extraction) | Epic and user story extraction from workshop materials | Business Analyst | | [tsh-task-quality-reviewing](./task-quality-review) | Quality analysis for extracted task lists | Business Analyst | -| [tsh-jira-task-formatting](./jira-task-formatting) | Jira-ready task formatting and import/push management | Business Analyst | +| [tsh-task-formatting](./task-formatting) | Task formatting for task management tools (Jira, Shortcut) — delegates to tool-specific sub-skills | Business Analyst | +| [tsh-using-task-and-knowledge-management-tools](./using-task-and-knowledge-management-tools) | Guidelines for interacting with task management (Jira, Shortcut) and knowledge base (Confluence) tools | Knowledge, Business Analyst | ### 🛠 Development Skills @@ -77,39 +78,40 @@ When an agent starts a task, it checks all available skills and decides which on ## Agent–Skill Matrix -| Skill | BA | CE | Architect | SE | PE | CR | UI Reviewer | E2E | DevOps | Copilot Eng. | -| -------------------------------------- | --- | --- | --------- | --- | --- | --- | ----------- | --- | ------ | ------------ | -| tsh-architecture-designing | | | ✅ | | | | | | | | -| tsh-code-reviewing | | | | | ✅ | ✅ | | | | | -| tsh-codebase-analysing | ✅ | ✅ | ✅ | ✅ | | | | | ✅ | ✅ | -| tsh-creating-agents | | | | | | | | | | ✅ | -| tsh-creating-instructions | | | | | | | | | | ✅ | -| tsh-creating-prompts | | | | | | | | | | ✅ | -| tsh-creating-skills | | | | | | | | | | ✅ | -| tsh-designing-multi-cloud-architecture | | | ✅ | | | | | | ✅ | | -| tsh-e2e-testing | | | | | | | | ✅ | | | -| tsh-engineering-prompts | | | ✅ | ✅ | ✅ | ✅ | | | | | -| tsh-ensuring-accessibility | | | | ✅ | | | | | | | -| tsh-implementing-ci-cd | | | ✅ | | | | | | ✅ | | -| tsh-implementing-forms | | | | ✅ | | | | | | | -| tsh-implementing-frontend | | | | ✅ | | | | | | | -| tsh-implementing-kubernetes | | | ✅ | | | | | | ✅ | | -| tsh-implementing-observability | | | ✅ | | | | | | ✅ | | -| tsh-implementing-terraform-modules | | | ✅ | | | | | | ✅ | | -| tsh-implementation-gap-analysing | | | ✅ | ✅ | | ✅ | | | | | -| tsh-jira-task-formatting | ✅ | | | | | | | | | | -| tsh-managing-secrets | | | ✅ | | | | | | ✅ | | -| tsh-optimizing-cloud-cost | | | ✅ | | | | | | ✅ | | -| tsh-optimizing-frontend | | | | ✅ | | | | | | | -| tsh-reviewing-frontend | | | | | | ✅ | | | | | -| tsh-sql-and-database-understanding | | | ✅ | ✅ | | ✅ | | | | | -| tsh-task-analysing | | ✅ | | | | | | ✅ | | | -| tsh-task-extracting | ✅ | | | | | | | | | | -| tsh-task-quality-reviewing | ✅ | | | | | | | | | | -| tsh-technical-context-discovering | | ✅ | ✅ | ✅ | ✅ | ✅ | | ✅ | ✅ | ✅ | -| tsh-transcript-processing | ✅ | | | | | | | | | | -| tsh-ui-verifying | | | | ✅ | | | ✅ | | | | -| tsh-writing-hooks | | | | ✅ | | | | | | | +| Skill | BA | CE | Architect | SE | PE | CR | UI Reviewer | E2E | DevOps | Copilot Eng. | Knowledge | +| -------------------------------------- | --- | --- | --------- | --- | --- | --- | ----------- | --- | ------ | ------------ | --------- | +| tsh-architecture-designing | | | ✅ | | | | | | | | | +| tsh-code-reviewing | | | | | ✅ | ✅ | | | | | | +| tsh-codebase-analysing | ✅ | ✅ | ✅ | ✅ | | | | | ✅ | ✅ | | +| tsh-creating-agents | | | | | | | | | | ✅ | | +| tsh-creating-instructions | | | | | | | | | | ✅ | | +| tsh-creating-prompts | | | | | | | | | | ✅ | | +| tsh-creating-skills | | | | | | | | | | ✅ | | +| tsh-designing-multi-cloud-architecture | | | ✅ | | | | | | ✅ | | | +| tsh-e2e-testing | | | | | | | | ✅ | | | | +| tsh-engineering-prompts | | | ✅ | ✅ | ✅ | ✅ | | | | | | +| tsh-ensuring-accessibility | | | | ✅ | | | | | | | | +| tsh-implementing-ci-cd | | | ✅ | | | | | | ✅ | | | +| tsh-implementing-forms | | | | ✅ | | | | | | | | +| tsh-implementing-frontend | | | | ✅ | | | | | | | | +| tsh-implementing-kubernetes | | | ✅ | | | | | | ✅ | | | +| tsh-implementing-observability | | | ✅ | | | | | | ✅ | | | +| tsh-implementing-terraform-modules | | | ✅ | | | | | | ✅ | | | +| tsh-implementation-gap-analysing | | | ✅ | ✅ | | ✅ | | | | | | +| tsh-task-formatting | ✅ | | | | | | | | | | | +| tsh-managing-secrets | | | ✅ | | | | | | ✅ | | | +| tsh-optimizing-cloud-cost | | | ✅ | | | | | | ✅ | | | +| tsh-optimizing-frontend | | | | ✅ | | | | | | | | +| tsh-reviewing-frontend | | | | | | ✅ | | | | | | +| tsh-sql-and-database-understanding | | | ✅ | ✅ | | ✅ | | | | | | +| tsh-task-analysing | | ✅ | | | | | | ✅ | | | | +| tsh-task-extracting | ✅ | | | | | | | | | | | +| tsh-task-quality-reviewing | ✅ | | | | | | | | | | | +| tsh-technical-context-discovering | | ✅ | ✅ | ✅ | ✅ | ✅ | | ✅ | ✅ | ✅ | | +| tsh-transcript-processing | ✅ | | | | | | | | | | | +| tsh-ui-verifying | | | | ✅ | | | ✅ | | | | | +| tsh-using-task-and-knowledge-management-tools | ✅ | | | | | | | | | | ✅ | +| tsh-writing-hooks | | | | ✅ | | | | | | | | ## Loading Priority diff --git a/website/docs/skills/jira-task-formatting.md b/website/docs/skills/task-formatting.md similarity index 50% rename from website/docs/skills/jira-task-formatting.md rename to website/docs/skills/task-formatting.md index fc055faa..2aa604a9 100644 --- a/website/docs/skills/jira-task-formatting.md +++ b/website/docs/skills/task-formatting.md @@ -1,69 +1,78 @@ --- sidebar_position: 15 -title: Jira Task Formatting +title: Task Formatting --- -# Jira Task Formatting +# Task Formatting -**Folder:** `.github/skills/tsh-jira-task-formatting/` +**Folder:** `.github/skills/tsh-task-formatting/` **Used by:** Business Analyst -Transforms extracted epics and user stories into Jira-ready format following a benchmark template. Handles field mapping, Jira markdown compatibility, two-gate user review, and Jira issue creation via Atlassian tools. Also supports importing existing Jira issues for local iteration. +Transforms extracted epics and user stories into a format supported by your task management system. This is a parent skill that delegates to tool-specific sub-skills based on the target platform: + +- **Jira** — `tsh-jira-task-formatting` (sub-skill) +- **Shortcut** — `tsh-shortcut-task-formatting` (sub-skill) + +Both sub-skills apply a consistent benchmark template to every task, validate completeness, and manage a two-gate review process before any stories are created. They also support importing existing issues for local iteration. ## Process -### Step 1: Load Template and Tasks +### Step 1: Determine Target Tool + +The skill identifies which task management tool to use (Jira or Shortcut) based on user input or project context, then delegates to the appropriate sub-skill. + +### Step 2: Load Template and Tasks -Load the benchmark template (`jira-task.example.md`) and the extracted tasks document (`extracted-tasks.md`). +Load the benchmark template and the extracted tasks document (`extracted-tasks.md`). -### Step 2: Format Epics +### Step 3: Format Epics -For each epic, create a Jira-ready entry with: +For each epic, create an entry formatted for the target tool with: - Summary (title) following naming conventions. - Structured description with business overview, value statement, and success metrics. - Acceptance criteria and labels. - Priority mapping (Critical → Highest, High → High, etc.). -### Step 3: Format Stories +### Step 5: Format Stories -For each story, create a Jira-ready entry with: +For each story, create an entry formatted for the target tool with: - Summary following naming conventions. - Structured description with context, user story format, requirements, and technical notes. - Acceptance criteria as Jira-compatible checklists. - Sizing guidance (Small / Medium / Large). - Parent epic reference and labels. -### Step 4: Validate Completeness +### Step 6: Validate Completeness Cross-check all tasks against the benchmark template for required fields, structure, and consistency. -### Step 5: Formatting Review (Gate 2 - Part 1) +### Step 7: Formatting Review (Gate 2 - Part 1) Present formatted output to the user. Review any changes made during formatting. -### Step 6: Save Output +### Step 8: Save Output -Save the Jira-ready tasks to `specifications//jira-tasks.md`. +Save the formatted tasks to `specifications//formatted-tasks.md`. -### Step 7: Push Approval (Gate 2 - Part 2) +### Step 9: Push Approval (Gate 2 - Part 2) -Confirm target Jira project, get explicit approval, then create/update issues in Jira. +Confirm the target project in the task management tool, get explicit approval, then create/update issues. Push operations are delegated to the [Knowledge](../agents/knowledge) agent. ## Import Mode -An alternative entry point for working with existing Jira backlogs: +An alternative entry point for working with existing backlogs: -1. **Identify target** — Jira project key, specific epic keys, or JQL query. -2. **Fetch issues** — Pull epics and their child stories from Jira. -3. **Map to template** — Convert Jira fields to the benchmark format. -4. **Generate local file** — Create `jira-tasks.md` with Jira keys pre-populated. +1. **Identify target** — Project key, specific epic keys, or a query. +2. **Fetch issues** — Pull epics and their child stories from the task management tool (via the [Knowledge](../agents/knowledge) agent). +3. **Map to template** — Convert fields to the benchmark format. +4. **Generate local file** — Create `formatted-tasks.md` with issue keys pre-populated. 5. **User review** — Present imported tasks for validation. -After import, changes can be pushed back to Jira individually or in batch. +After import, changes can be pushed back individually or in batch. ## Jira Markdown Compatibility -When creating issues in Jira, the skill converts standard markdown to Jira format: +When creating issues in Jira (via the Jira sub-skill), standard markdown is converted to Jira format: | Standard Markdown | Jira Format | |---|---| @@ -75,16 +84,16 @@ When creating issues in Jira, the skill converts standard markdown to Jira forma | `` `code` `` | `{code}...{code}` | :::note -The local markdown file uses standard markdown formatting. Jira-specific formatting is applied only when creating the actual issues. +The local markdown file uses standard markdown formatting. Jira-specific formatting is applied only when creating the actual issues. Shortcut uses standard markdown natively. ::: ## Per-Change Modification Flow When the user modifies a specific task outside the main workflow: -1. Update the local `jira-tasks.md` first. -2. Ask the user whether to push the change to Jira now. -3. If yes, update the specific Jira issue using its key. +1. Update the local `formatted-tasks.md` first. +2. Ask the user whether to push the change now. +3. If yes, update the specific issue using its key (via the [Knowledge](../agents/knowledge) agent). 4. If no, the change remains local until the next batch push. ## Protected Status Guard @@ -94,7 +103,7 @@ Tasks with a protected status (**Done**, **Cancelled**, or **PO APPROVE**) canno - **Formatting** — Protected tasks are preserved exactly as imported. No reformatting, rewriting, or field changes. Marked with a `🔒` indicator. - **Validation** — Completeness checks are skipped for protected tasks; their content is not subject to benchmark compliance. - **User Review** — Protected tasks are not flagged for user attention; their fields are read-only. -- **Per-Change Modifications** — If a user requests changes to a protected task, the agent informs them the task cannot be modified and suggests updating the status in Jira first, then re-importing. +- **Per-Change Modifications** — If a user requests changes to a protected task, the agent informs them the task cannot be modified and suggests updating the status in the task management tool first, then re-importing. - **Import** — After mapping fields, each imported task's status is checked. Protected tasks are marked as read-only with a `🔒` indicator and preserved as-is. ## Connected Skills diff --git a/website/docs/skills/task-quality-review.md b/website/docs/skills/task-quality-review.md index 7152e0ca..268838dd 100644 --- a/website/docs/skills/task-quality-review.md +++ b/website/docs/skills/task-quality-review.md @@ -79,4 +79,4 @@ Apply accepted suggestions to `extracted-tasks.md` and save the quality review r ## Connected Skills - `tsh-task-extracting` — Provides the extracted tasks used as primary input. -- `tsh-jira-task-formatting` — Consumes the updated task list after quality review. +- `tsh-task-formatting` — Consumes the updated task list after quality review. diff --git a/website/docs/skills/using-task-and-knowledge-management-tools.md b/website/docs/skills/using-task-and-knowledge-management-tools.md new file mode 100644 index 00000000..7407134a --- /dev/null +++ b/website/docs/skills/using-task-and-knowledge-management-tools.md @@ -0,0 +1,49 @@ +--- +sidebar_position: 16 +title: Using Task & Knowledge Management Tools +--- + +# Using Task & Knowledge Management Tools + +**Folder:** `.github/skills/tsh-using-task-and-knowledge-management-tools/` +**Used by:** Knowledge, Business Analyst + +Guidelines for accessing and using task management and knowledge base tools to retrieve and update information related to tasks, projects, and documentation. This is a parent skill that delegates to tool-specific sub-skills based on the target platform: + +- **Jira and Confluence** — `tsh-using-atlassian` (sub-skill) +- **Shortcut** — `tsh-using-shortcut` (sub-skill) + +## Supported Tools + +### Task Management +| Tool | Sub-skill | +|---|---| +| **Atlassian Jira** | `tsh-using-atlassian` | +| **Shortcut** | `tsh-using-shortcut` | + +### Knowledge Base +| Tool | Sub-skill | +|---|---| +| **Atlassian Confluence** | `tsh-using-atlassian` | + +## How It Works + +When an agent needs to interact with a task management or knowledge base tool, this skill: + +1. **Identifies the target tool** — Based on project context, user preferences, or VS Code memory. +2. **Delegates to the appropriate sub-skill** — Routes to `tsh-using-atlassian` for Jira/Confluence operations or `tsh-using-shortcut` for Shortcut operations. +3. **Provides common guidelines** — Covers resource discovery, workspace selection, error handling, and data integrity practices that apply across all tools. + +## Key Principles + +- **Discover before acting** — Always identify the correct workspace and tool preferences before performing operations. +- **Separate task management and knowledge base** — Don't assume the same tool is used for both. A project may use Jira for tasks and Confluence for docs. +- **Human-in-the-loop for writes** — All create/update operations should be confirmed with the user before execution. +- **Data integrity** — Never overwrite data without explicit approval. Prefer additive changes over destructive ones. +- **Error handling** — Report failures clearly and suggest resolution steps rather than retrying silently. + +## Connected Skills + +- `tsh-task-formatting` — Formats tasks before they are pushed to the task management tool. +- `tsh-task-extracting` — Provides the extracted tasks that get pushed after formatting. +- `tsh-task-quality-reviewing` — Reviews task quality before formatting and push. diff --git a/website/docs/use-cases.md b/website/docs/use-cases.md index 81f55172..a5933f94 100644 --- a/website/docs/use-cases.md +++ b/website/docs/use-cases.md @@ -11,11 +11,11 @@ Nine scenarios where Copilot Collections changes how work actually gets done. ## Product Ideation -### Workshop transcripts → Jira backlog in 15 minutes +### Workshop transcripts → structured backlog in 15 minutes -You've just run a discovery workshop. The transcript is a mess of raw ideas, half-formed requirements, and branching conversations. Turning that into a well-structured, ticket-ready backlog normally takes a BA a day or two, if you have one. If you don't, it falls to a developer or PM, and it shows. +You’ve just run a discovery workshop. The transcript is a mess of raw ideas, half-formed requirements, and branching conversations. Turning that into a well-structured, ticket-ready backlog normally takes a BA a day or two, if you have one. If you don’t, it falls to a developer or PM, and it shows. -The Business Analyst agent processes the raw materials end-to-end. Transcripts are cleaned and structured. Epics and user stories are extracted with acceptance criteria, edge cases, and dependencies surfaced. A 10-pass quality review checks for missing entity lifecycles, error states, notification gaps, and off-happy-path scenarios. Nothing reaches Jira without passing a three-gate human review. +The Business Analyst agent processes the raw materials end-to-end. Transcripts are cleaned and structured. Epics and user stories are extracted with acceptance criteria, edge cases, and dependencies surfaced. A 10-pass quality review checks for missing entity lifecycles, error states, notification gaps, and off-happy-path scenarios. Nothing reaches your task management tool (Jira or Shortcut) without passing a three-gate human review. **~15 min vs 1–2 days** @@ -25,7 +25,7 @@ The Business Analyst agent processes the raw materials end-to-end. Transcripts a Backlogs accumulate debt. Stories that made sense six months ago are now vague. Acceptance criteria were never written. Dependencies were assumed, not documented. Grooming sessions spend half their time reconstructing intent rather than improving work. -The Business Analyst agent's Import Mode fetches existing Jira issues, converts them to a local format, and runs the same quality review used for new workshop outputs. Each suggested improvement is presented individually for accept or reject. Approved changes push back to Jira automatically. +The Business Analyst agent’s Import Mode fetches existing issues from Jira or Shortcut, converts them to a local format, and runs the same quality review used for new workshop outputs. Each suggested improvement is presented individually for accept or reject. Approved changes push back to the task management tool automatically. **~10 min per epic** @@ -37,7 +37,7 @@ The Business Analyst agent's Import Mode fetches existing Jira issues, converts A developer joins mid-sprint. The standard onboarding is: read the README, ask questions in Slack, try to figure out the conventions, come back in three days when you have something to show. The first week is expensive. -The Context Engineer agent gathers context from Jira, Confluence, Figma, and the codebase automatically. The Architect agent turns that context into a step-by-step implementation plan scoped to the actual ticket. New developers get a structured picture of the task — what exists, what needs to change, where to start - in minutes, not days. +The Context Engineer agent gathers context from Jira or Shortcut, Confluence, Figma, and the codebase automatically. The Architect agent turns that context into a step-by-step implementation plan scoped to the actual ticket. New developers get a structured picture of the task — what exists, what needs to change, where to start - in minutes, not days. **~5 min per task** @@ -47,7 +47,7 @@ The Context Engineer agent gathers context from Jira, Confluence, Figma, and the The information needed to implement any feature lives across four tools at minimum. Developers spend 30–60 minutes per task reconstructing context that already exists — just in different places. -MCP integrations (Atlassian, Figma, Context7, Playwright, PDF Reader) bring every source into a single Copilot chat session. The Context Engineer agent synthesises them into one research document. You start implementing with full context already assembled. +MCP integrations (Atlassian, Shortcut, Figma, Context7, Playwright, PDF Reader) bring every source into a single Copilot chat session. The Context Engineer agent synthesises them into one research document. You start implementing with full context already assembled. **~3 min vs 30–60 min** diff --git a/website/docs/workflow/frontend-flow.md b/website/docs/workflow/frontend-flow.md index bfb15a6c..0fc2a907 100644 --- a/website/docs/workflow/frontend-flow.md +++ b/website/docs/workflow/frontend-flow.md @@ -10,21 +10,16 @@ For UI-heavy tasks with Figma designs, use the specialized frontend workflow. Th ## Command Sequence ```text -1️⃣ /tsh-research - ↳ 📖 Review research doc – verify Figma links, requirements - ↳ ✅ Iterate until context is complete and accurate - -2️⃣ /tsh-plan - ↳ 📖 Review plan – check component breakdown, design references - ↳ ✅ Confirm phases align with Figma structure - -3️⃣ /tsh-implement +1️⃣ /tsh-implement + ↳ 📖 Internal research phase — Context Engineer gathers requirements, Figma links, codebase context + ↳ 📖 Internal planning phase — Architect creates component breakdown with design references + ↳ ✅ Review research doc and plan — verify Figma links, confirm phases align with Figma structure ↳ 📖 Engineering Manager delegates UI tasks to Software Engineer ↳ 📖 Review code changes and UI Verification Summary ↳ ✅ Manually verify critical UI elements in browser ↳ 🔄 Engineering Manager calls /tsh-review-ui in a loop until PASS or escalation -4️⃣ /tsh-review +2️⃣ /tsh-review ↳ 📖 Review findings – code quality, a11y, performance ↳ ✅ Address all blockers before merging ``` diff --git a/website/docs/workflow/overview.md b/website/docs/workflow/overview.md index 4ed3989e..d2854c4b 100644 --- a/website/docs/workflow/overview.md +++ b/website/docs/workflow/overview.md @@ -5,9 +5,9 @@ title: Workflow Overview # Workflow Overview -Copilot Collections is an AI product engineering framework that covers the **full product lifecycle** through a structured 5-phase workflow: +Copilot Collections is an AI product engineering framework that covers the **full product lifecycle** through a structured workflow: -> **Ideate → Research → Plan → Implement → Review** +> **Ideate → Implement → Review** Each phase is executed by a specialized agent and produces a documented artifact that feeds the next phase. This ensures consistent, high-quality outputs across teams — from workshop materials all the way to production-ready, reviewed code. @@ -15,7 +15,7 @@ Each phase is executed by a specialized agent and produces a documented artifact Think of this workflow as a **relay race**. Each phase produces a deliverable — the "baton" — that is reviewed by the human and then passed to the next phase. Workshop materials feed the backlog, the research document feeds the plan, the plan feeds the implementation, and the implementation feeds the review. Nothing is lost between steps, and every handoff is a documented artifact. ::: -## The 5 Phases +## The 3 Phases ### 1. Ideate @@ -23,39 +23,23 @@ Think of this workflow as a **relay race**. Each phase produces a deliverable - **Command:** `/tsh-analyze-materials ` - Processes raw workshop materials (transcripts, Figma designs, documents) into structured epics and stories. - Runs 10-pass quality review with three mandatory human review gates. -- **Produces:** Jira-ready epics and stories with acceptance criteria, dependencies, and priorities. +- **Produces:** Epics and stories formatted for your task management tool (Jira or Shortcut) with acceptance criteria, dependencies, and priorities. -### 2. Research - -- **Agent:** Context Engineer -- **Command:** `/tsh-research ` -- Builds context around a task using Jira, Figma, and other integrated tools. -- Identifies missing information, risks, and open questions. -- **Produces:** Research document (`.research.md`) with task summary, assumptions, open questions, and suggested next steps. - -### 3. Plan - -- **Agent:** Architect -- **Command:** `/tsh-plan ` -- Translates the task into a structured implementation plan. -- Breaks work into phases and executable steps. -- **Produces:** Implementation plan (`.plan.md`) with checklist-style phases, acceptance criteria, and technical constraints. - -### 4. Implement +### 2. Implement - **Agent:** Engineering Manager (orchestrates specialized agents) -- **Command:** `/tsh-implement ` +- **Command:** `/tsh-implement ` - Automatically handles the full development cycle: - 1. **Research** — Delegates to Context Engineer to gather context from Jira, Figma, and codebase. Asks for user confirmation before proceeding. + 1. **Research** — Delegates to Context Engineer to gather context from Jira/Shortcut, Figma, and codebase. Asks for user confirmation before proceeding. 2. **Plan** — Delegates to Architect to create a structured implementation plan. Asks for user confirmation before proceeding. - 3. **Implement** — Delegates to Software Engineer, Prompt Engineer, DevOps Engineer, or E2E Engineer based on task type. + 3. **Implement** — Delegates to Software Engineer, Prompt Engineer, DevOps Engineer, E2E Engineer, or Knowledge agent based on task type. - Tracks progress, runs quality checks after each task, and auto-triggers code review. -- **Produces:** Concrete code modifications scoped to the task, applied by delegated agents. +- **Produces:** Research document (`.research.md`), implementation plan (`.plan.md`), and concrete code modifications scoped to the task. -### 5. Review +### 3. Review - **Agent:** Code Reviewer -- **Command:** `/tsh-review ` +- **Command:** `/tsh-review ` - Performs a structured code review against acceptance criteria, security, reliability, and maintainability. - **Produces:** Structured review with clear pass/blockers/suggestions. @@ -75,7 +59,7 @@ Each step requires your review and verification. Open the generated documents, g The full lifecycle has specialized variants for different task types: -- **[Workshop Analysis Flow](./workshop-flow)** — Convert discovery workshop materials into Jira-ready epics and stories using `/tsh-analyze-materials`. -- **[Standard Flow](./standard-flow)** — Backend/fullstack tasks using `/tsh-research` → `/tsh-plan` → `/tsh-implement` → `/tsh-review`. +- **[Workshop Analysis Flow](./workshop-flow)** — Convert discovery workshop materials into structured epics and stories for Jira or Shortcut using `/tsh-analyze-materials`. +- **[Standard Flow](./standard-flow)** — Backend/fullstack tasks using `/tsh-implement` → `/tsh-review`. - **[Frontend Flow](./frontend-flow)** — UI tasks with Figma verification using `/tsh-implement` (which internally uses `/tsh-implement-ui`) and `/tsh-review-ui`. - **[E2E Testing Flow](./e2e-flow)** — End-to-end test creation delegated by the Engineering Manager to the E2E Engineer via `/tsh-implement`. diff --git a/website/docs/workflow/standard-flow.md b/website/docs/workflow/standard-flow.md index 38cd60c1..49f09b69 100644 --- a/website/docs/workflow/standard-flow.md +++ b/website/docs/workflow/standard-flow.md @@ -33,7 +33,7 @@ The Engineering Manager automatically handles the full development cycle: #### Implementation Phase -- **Delegated to:** Software Engineer, Prompt Engineer, DevOps Engineer, E2E Engineer (based on task type) +- **Delegated to:** Software Engineer, Prompt Engineer, DevOps Engineer, E2E Engineer, Knowledge (based on task type) - **What it does:** Executes the plan by delegating to specialized agents. Tracks progress and runs quality checks after each task. - **What it produces:** Concrete code modifications applied by delegated agents. - **Your action:** Review code changes after each phase. Test functionality. Verify against the plan. diff --git a/website/docs/workflow/workshop-flow.md b/website/docs/workflow/workshop-flow.md index d8dd9336..4e9f0d72 100644 --- a/website/docs/workflow/workshop-flow.md +++ b/website/docs/workflow/workshop-flow.md @@ -5,7 +5,7 @@ title: Workshop Analysis Flow # Workshop Analysis Flow -For converting discovery workshop materials into structured, Jira-ready epics and user stories, use the Workshop Analysis workflow. This takes raw workshop outputs (transcripts, designs, notes) and produces a validated backlog ready for team refinement. +For converting discovery workshop materials into structured epics and user stories for your task management tool (Jira or Shortcut), use the Workshop Analysis workflow. This takes raw workshop outputs (transcripts, designs, notes) and produces a validated backlog ready for team refinement. ## Command Sequence @@ -25,10 +25,10 @@ For converting discovery workshop materials into structured, Jira-ready epics an ↳ 📖 Review each suggestion — accept or reject individually ↳ ✅ Agent applies accepted suggestions to the task list -4️⃣ Gate 2 — Jira Push Approval +4️⃣ Gate 2 — Push Approval ↳ 📖 Review final formatted tasks - ↳ ✅ Confirm target Jira project and approve push - ↳ 🚀 Agent creates/updates issues in Jira + ↳ ✅ Confirm target project and approve push + ↳ 🚀 Agent creates/updates issues via Knowledge agent ``` ## Workflow Diagram @@ -63,8 +63,8 @@ For converting discovery workshop materials into structured, Jira-ready epics an └──────────┬──────────────────┘ ▼ ┌─────────────────────────────┐ -│ Jira Formatting │ -│ → jira-tasks.md │ +│ Task Formatting │ +│ → formatted-tasks.md │ └──────────┬──────────────────┘ ▼ ┌─────────────────────────────┐ @@ -72,8 +72,8 @@ For converting discovery workshop materials into structured, Jira-ready epics an └──────────┬──────────────────┘ ▼ ┌─────────────────────────────┐ -│ Push to Jira │ -│ (create epics → stories) │ +│ Push to Task Mgmt Tool │ +│ (via Knowledge agent) │ └─────────────────────────────┘ ``` @@ -96,13 +96,13 @@ The quality review step runs 10 domain-agnostic analysis passes against the appr ## Import Mode -To iterate on an existing Jira backlog instead of workshop materials: +To iterate on an existing backlog instead of workshop materials: ```text /tsh-analyze-materials PROJ-123 ``` -The agent fetches existing issues from Jira, converts them into the local format, then runs quality review and formatting. Changes can be pushed back to Jira individually or in batch. +The agent fetches existing issues from the task management tool (via the Knowledge agent), converts them into the local format, then runs quality review and formatting. Changes can be pushed back individually or in batch. ## Connecting to the Standard Flow diff --git a/website/src/components/SdlcDiagram/index.tsx b/website/src/components/SdlcDiagram/index.tsx index 9a420938..5ae123a9 100644 --- a/website/src/components/SdlcDiagram/index.tsx +++ b/website/src/components/SdlcDiagram/index.tsx @@ -32,12 +32,24 @@ export default function SdlcDiagram(): React.JSX.Element {
/tsh-analyze-materials + Business Analyst
- Clean transcript → extract tasks → produce Jira-ready stories with + Clean transcript → extract tasks → produce stories with full acceptance criteria
+
↓ delegates to
+
+
+
+ Knowledge +
+
+ Task & knowledge management +
+
+
@@ -106,6 +118,14 @@ export default function SdlcDiagram(): React.JSX.Element { LLM application prompts
+
+
+ Knowledge +
+
+ Task & knowledge management +
+
From 0c66361b35ef1648df39ae00d2e0875cea527f4f Mon Sep 17 00:00:00 2001 From: Adam Polak Date: Sun, 29 Mar 2026 23:04:21 +0200 Subject: [PATCH 4/4] feat: refactored skills to use subskills --- .github/agents/tsh-business-analyst.agent.md | 9 ++++----- .github/agents/tsh-knowledge.agent.md | 3 +-- .github/prompts/tsh-analyze-materials.prompt.md | 8 +++----- .github/skills/tsh-task-formatting/SKILL.md | 10 ++++++++++ .../tsh-jira-task-formatting/SKILL.md | 0 .../tsh-jira-task-formatting/jira-task.example.md | 0 .../tsh-shortcut-task-formatting/SKILL.md | 0 .../shortcut-task.example.md | 0 .github/skills/tsh-task-quality-reviewing/SKILL.md | 5 ++--- .../SKILL.md | 10 ++++++++++ .../tsh-using-atlassian/SKILL.md | 2 +- .../tsh-using-shortcut/SKILL.md | 0 12 files changed, 31 insertions(+), 16 deletions(-) create mode 100644 .github/skills/tsh-task-formatting/SKILL.md rename .github/skills/{ => tsh-task-formatting}/tsh-jira-task-formatting/SKILL.md (100%) rename .github/skills/{ => tsh-task-formatting}/tsh-jira-task-formatting/jira-task.example.md (100%) rename .github/skills/{ => tsh-task-formatting}/tsh-shortcut-task-formatting/SKILL.md (100%) rename .github/skills/{ => tsh-task-formatting}/tsh-shortcut-task-formatting/shortcut-task.example.md (100%) create mode 100644 .github/skills/tsh-using-task-and-knowledge-management-tools/SKILL.md rename .github/skills/{ => tsh-using-task-and-knowledge-management-tools}/tsh-using-atlassian/SKILL.md (98%) rename .github/skills/{ => tsh-using-task-and-knowledge-management-tools}/tsh-using-shortcut/SKILL.md (100%) diff --git a/.github/agents/tsh-business-analyst.agent.md b/.github/agents/tsh-business-analyst.agent.md index 427ecf89..4c58c35f 100644 --- a/.github/agents/tsh-business-analyst.agent.md +++ b/.github/agents/tsh-business-analyst.agent.md @@ -59,10 +59,9 @@ This policy is the **single source of truth** for the protected status list. All - `tsh-transcript-processing` - to clean raw workshop transcripts from small talk, structure by topics, and extract key decisions, action items, and open questions. Use at the beginning of the workflow when raw transcripts are provided. - `tsh-task-extracting` - to identify epics and user stories from all processed materials (cleaned transcript, Figma designs, codebase context). Use after transcript processing and material analysis are complete. -- `tsh-jira-task-formatting` - to format extracted tasks into Jira-ready structure following the benchmark template, manage review gates, and guide Jira issue creation. Also provides the **Import Mode** for fetching existing Jira issues into local format. Use when **Jira** is the target task management tool. -- `tsh-shortcut-task-formatting` - to format extracted tasks into Shortcut-ready structure following the benchmark template, manage review gates, and guide Shortcut story creation. Also provides the **Import Mode** for fetching existing Shortcut stories into local format. Use when **Shortcut** is the target task management tool. -- `tsh-using-atlassian` - guidelines for interacting with Jira and Confluence via Atlassian MCP tools. Covers resource discovery, workspace selection, and common operations. Load when using Jira/Confluence. -- `tsh-using-shortcut` - guidelines for interacting with Shortcut via Shortcut MCP tools. Covers workspace context discovery and common operations. Load when using Shortcut. + +- `tsh-task-formatting` - to format extracted tasks into the structure required by the target task management system (Jira or Shortcut). This skill orchestrates the formatting process and delegates to specific formatting skills based on the target tool. Use after quality review is complete and before pushing to the task management tool. Also use for the **Import Mode** when the user provides existing task IDs or a project key instead of workshop materials. +- `tsh-using-task-and-knowledge-management-tools` - for guidelines on interacting with task management and knowledge base tools to retrieve and update information related to tasks, projects, and documentation Covers resource discovery, workspace selection, and common operations. Load when using any task management or knowledge base tool. - `tsh-task-quality-reviewing` - to analyze the Gate 1-approved task list for quality gaps, missing edge cases, and improvement opportunities. Runs automatically after Gate 1 approval. Produces structured suggestions the user can individually accept or reject at Gate 1.5, then applies accepted changes to `extracted-tasks.md`. - `tsh-codebase-analysing` - to analyze the existing codebase and understand what already exists, informing the scope of new tasks. Use during material analysis when codebase context is relevant. @@ -164,7 +163,7 @@ You have access to the `tsh-knowledge` agent for interacting with Task Managemen - Fetching existing epics and stories from Task Management Tool when the user wants to iterate on an existing backlog. - Updating individual Task Management Tool issues when the user modifies a task that has a Task Management Tool key in `formatted-tasks.md`. - **IMPORTANT**: - - Always establish workspace context first using the appropriate tool interaction skill (`tsh-using-atlassian` or `tsh-using-shortcut`). + - Always establish workspace context first using the appropriate tool interaction skill (`tsh-using-task-and-knowledge-management-tools`). - If there is more than one accessible resource, ask the user which one to use before proceeding. - Create epics first to obtain their Task Management Tool IDs, then create stories linked to those epics. - Before batch-pushing, check each task's `Task Management Tool Key` field. Tasks with existing keys are **updated**, not recreated. Present a sync summary to the user showing: (a) tasks to be CREATED (no Task Management Tool key), (b) tasks to be UPDATED (existing key), (c) total counts. Get approval before proceeding. diff --git a/.github/agents/tsh-knowledge.agent.md b/.github/agents/tsh-knowledge.agent.md index 46f6c3ea..37fc6e10 100644 --- a/.github/agents/tsh-knowledge.agent.md +++ b/.github/agents/tsh-knowledge.agent.md @@ -30,8 +30,7 @@ For Knowledge Base we support: ## Skills Usage Guidelines -- `tsh-using-atlassian` - guidelines for interacting with Jira and Confluence via Atlassian MCP tools. Covers resource discovery, workspace selection, searching, reading, creating and updating issues and pages. Load when using `atlassian/*` tools. -- `tsh-using-shortcut` - guidelines for interacting with Shortcut via Shortcut MCP tools. Covers workspace context discovery and common operations for stories, epics, iterations, and documents. Load when using `shortcut/*` tools. +- `tsh-using-task-and-knowledge-management-tools` - guidelines for interacting with supported task management and knowledge base tools (Atlassian Jira and Confluence, Shortcut) to retrieve and update information related to tasks, projects, and documentation. ## Tool Usage Guidelines diff --git a/.github/prompts/tsh-analyze-materials.prompt.md b/.github/prompts/tsh-analyze-materials.prompt.md index 033e7fcf..8597b831 100644 --- a/.github/prompts/tsh-analyze-materials.prompt.md +++ b/.github/prompts/tsh-analyze-materials.prompt.md @@ -18,17 +18,15 @@ Before starting, load and follow these skills in order: - `tsh-transcript-processing` - for cleaning and structuring raw transcripts - `tsh-task-extracting` - for identifying epics and user stories from all materials - `tsh-task-quality-reviewing` - for analyzing extracted tasks for gaps, edge cases, and improvements -- `tsh-jira-task-formatting` (when target is Jira) - for formatting tasks per the benchmark template and managing Jira push -- `tsh-shortcut-task-formatting` (when target is Shortcut) - for formatting tasks per the benchmark template and managing Shortcut push -- `tsh-using-atlassian` - for accessing Jira and Confluence when target is Jira -- `tsh-using-shortcut` - for accessing Shortcut when target is Shortcut +- `tsh-task-formatting` - for orchestrating the formatting process and delegating to specific formatting skills based on the target tool +- `tsh-using-task-and-knowledge-management-tools` - for guidelines on interacting with task management and knowledge base tools to retrieve and update information related to tasks, projects, and documentation - `tsh-codebase-analysing` - for understanding the existing codebase when relevant ## Workflow Determine the entry point based on what the user provides: -**If the user provides existing task IDs (Jira issue keys or Shortcut story IDs) or a project key instead of workshop materials**, skip transcript processing and task extraction. Use the appropriate formatting skill (`tsh-jira-task-formatting` or `tsh-shortcut-task-formatting`) **Import Mode** to fetch and convert existing tasks into `formatted-tasks.md`. Then proceed to quality review (Step 5) and formatting. +**If the user provides existing task IDs (Jira issue keys or Shortcut story IDs) or a project key instead of workshop materials**, skip transcript processing and task extraction. Use the appropriate formatting skill (`tsh-task-formatting`) **Import Mode** to fetch and convert existing tasks into `formatted-tasks.md`. Then proceed to quality review (Step 5) and formatting. **Standard workflow (workshop materials provided):** diff --git a/.github/skills/tsh-task-formatting/SKILL.md b/.github/skills/tsh-task-formatting/SKILL.md new file mode 100644 index 00000000..7098ae2d --- /dev/null +++ b/.github/skills/tsh-task-formatting/SKILL.md @@ -0,0 +1,10 @@ +--- +name: tsh-task-formatting +description: This skill hellps you transform an extracted task list (epics and user stories) into a format supported by your task management system (e.g., Shortcut, Jira). It applies a consistent benchmark template to every task, validates completeness, and manages a two-gate review process before any stories are created. +--- + +# Supported Task Management Systems + +Delegate to specific skill when formatting tasks for different task management systems: +- when formatting for Shortcut, delegate to [`./tsh-shortcut-task-formatting`](./tsh-shortcut-task-formatting/SKILL.md) skill +- when formatting for Jira, delegate to [`./tsh-jira-task-formatting`](./tsh-jira-task-formatting/SKILL.md) skill diff --git a/.github/skills/tsh-jira-task-formatting/SKILL.md b/.github/skills/tsh-task-formatting/tsh-jira-task-formatting/SKILL.md similarity index 100% rename from .github/skills/tsh-jira-task-formatting/SKILL.md rename to .github/skills/tsh-task-formatting/tsh-jira-task-formatting/SKILL.md diff --git a/.github/skills/tsh-jira-task-formatting/jira-task.example.md b/.github/skills/tsh-task-formatting/tsh-jira-task-formatting/jira-task.example.md similarity index 100% rename from .github/skills/tsh-jira-task-formatting/jira-task.example.md rename to .github/skills/tsh-task-formatting/tsh-jira-task-formatting/jira-task.example.md diff --git a/.github/skills/tsh-shortcut-task-formatting/SKILL.md b/.github/skills/tsh-task-formatting/tsh-shortcut-task-formatting/SKILL.md similarity index 100% rename from .github/skills/tsh-shortcut-task-formatting/SKILL.md rename to .github/skills/tsh-task-formatting/tsh-shortcut-task-formatting/SKILL.md diff --git a/.github/skills/tsh-shortcut-task-formatting/shortcut-task.example.md b/.github/skills/tsh-task-formatting/tsh-shortcut-task-formatting/shortcut-task.example.md similarity index 100% rename from .github/skills/tsh-shortcut-task-formatting/shortcut-task.example.md rename to .github/skills/tsh-task-formatting/tsh-shortcut-task-formatting/shortcut-task.example.md diff --git a/.github/skills/tsh-task-quality-reviewing/SKILL.md b/.github/skills/tsh-task-quality-reviewing/SKILL.md index 2f37f74f..f0030665 100644 --- a/.github/skills/tsh-task-quality-reviewing/SKILL.md +++ b/.github/skills/tsh-task-quality-reviewing/SKILL.md @@ -58,7 +58,7 @@ Build a complete picture of the project scope, actors, and features before proce If Task Management tools are available and the user has indicated a project (either in their initial message or during the workflow): -1. Check available resources using the appropriate tool interaction guidelines (`tsh-using-atlassian` or `tsh-using-shortcut`). +1. Check available resources using the appropriate tool interaction guidelines (`tsh-using-task-and-knowledge-management-tools`). 2. If multiple resources exist, ask the user which one to use. 3. If the user provided a Task Management project key, use it. If not, ask once: "I have access to Task Management tools. Would you like me to check an existing board for additional context? If so, what is the project key?" If the user declines, skip this step entirely. 4. Fetch existing epics and stories from the board. @@ -325,5 +325,4 @@ The report serves as an audit trail documenting: ## Connected Skills - `tsh-task-extracting` — provides the extracted tasks used as primary input for the quality review -- `tsh-jira-task-formatting` — consumes the updated task list after quality review when using Jira -- `tsh-shortcut-task-formatting` — consumes the updated task list after quality review when using Shortcut +- `tsh-task-formatting` — consumes the updated task list after quality review when using Jira or Shortcut diff --git a/.github/skills/tsh-using-task-and-knowledge-management-tools/SKILL.md b/.github/skills/tsh-using-task-and-knowledge-management-tools/SKILL.md new file mode 100644 index 00000000..8dcca392 --- /dev/null +++ b/.github/skills/tsh-using-task-and-knowledge-management-tools/SKILL.md @@ -0,0 +1,10 @@ +--- +name: tsh-using-task-and-knowledge-management-tools +description: Guidelines for accessing and using task and knowledge management tools (e.g., Jira, Confluence, Shortcut, Notion) to retrieve and update information related to tasks, projects, and documentation. This skill covers best practices for interacting with these tools, including how to read and write data, handle errors, and ensure data integrity while collaborating with human users. +--- + +# Supported Tools +This skill provides guidelines for interacting with various task and knowledge management tools. For specific instructions on how to use each tool, delegate to the corresponding sub-skill: +- For Shortcut: delegate to [`./tsh-using-shortcut`](./tsh-using-shortcut/SKILL.md) skill +- For Jira and Confluence: delegate to [`./tsh-using-atlassian`](./tsh-using-atlassian/SKILL.md) skill + diff --git a/.github/skills/tsh-using-atlassian/SKILL.md b/.github/skills/tsh-using-task-and-knowledge-management-tools/tsh-using-atlassian/SKILL.md similarity index 98% rename from .github/skills/tsh-using-atlassian/SKILL.md rename to .github/skills/tsh-using-task-and-knowledge-management-tools/tsh-using-atlassian/SKILL.md index a08a6875..8b63f921 100644 --- a/.github/skills/tsh-using-atlassian/SKILL.md +++ b/.github/skills/tsh-using-task-and-knowledge-management-tools/tsh-using-atlassian/SKILL.md @@ -99,5 +99,5 @@ If the agent does not define a Protected Status Policy, use the defaults above. ## Connected Skills -- `tsh-jira-task-formatting` — uses Atlassian tools to push formatted tasks to Jira +- `tsh-task-formatting` — uses Atlassian tools to push formatted tasks to Jira - `tsh-task-quality-reviewing` — may use Atlassian tools to check board context during quality review diff --git a/.github/skills/tsh-using-shortcut/SKILL.md b/.github/skills/tsh-using-task-and-knowledge-management-tools/tsh-using-shortcut/SKILL.md similarity index 100% rename from .github/skills/tsh-using-shortcut/SKILL.md rename to .github/skills/tsh-using-task-and-knowledge-management-tools/tsh-using-shortcut/SKILL.md