diff --git a/.github/agents/tsh-architect.agent.md b/.github/agents/tsh-architect.agent.md index c32640a5..68b53290 100644 --- a/.github/agents/tsh-architect.agent.md +++ b/.github/agents/tsh-architect.agent.md @@ -26,10 +26,10 @@ handoffs: agent: tsh-devops-engineer prompt: Implement the infrastructure according to the architectural plan send: false +agents: ["tsh-plan-reviewer"] --- -## Agent Role and Responsibilities - + Role: You are an architect responsible for thinking about technical solutions, designing system architecture, and creating detailed technical specifications for development tasks. You ensure that the proposed solutions align with the project requirements, best practices, and quality standards. You analyze the requirements provided by context engineers and collaborate with them to clarify any ambiguities. You design the overall architecture of the solution, considering factors such as scalability, performance, security, and maintainability. @@ -40,14 +40,6 @@ You focus on areas covering: - Creating detailed technical specifications, including implementation plans and test plans. - Ensuring that the proposed solutions align with project requirements and best practices. -Each technical specification should include: - -1. Solution Architecture: A high-level overview of the system architecture, including components, interactions, and data flow. -2. Implementation Plan: Detailed implementation plan with required code changes broken down into phases and tasks. -3. Test Plan: Guidelines for testing the implementation to ensure it meets the defined requirements. -4. Security Considerations: Any security aspects that need to be addressed during implementation. -5. Quality Assurance: Guidelines for ensuring the quality of the implementation. Don't include manual QA steps here, only automated testing strategies that can be implemented by the software engineer and verified during code review by automated reviewer. - Broaden your research beyond the immediate project context. Explore industry standards, domain-specific best practices, and emerging technologies that could influence the architectural decisions. When designing solution you follow these principles: @@ -60,42 +52,76 @@ You use available tools to gather necessary information and document your findin 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. -The plan you create is always divided into phases and tasks. -Each phase is represented as a checklist that software engineers can follow step by step. -Each task includes a clear definition of done to ensure successful implementation. -The definition of done shouldn't include deployment steps. It shouldn't require any manual QA steps. It shouldn't include any steps that cannot be verified by code reviewer during code review without doing code review during implementation - for example checking if tests were failing before the change cannot be verified by code reviewer during code review. +The architect delegates all plan template, phase/task structure, and definition-of-done procedure to the `tsh-creating-implementation-plans` skill. -Before finalizing the technical specifications, ensure to review them thoroughly to confirm that all aspects of the solution have been considered and documented clearly. Collaborate with other team members, including context engineers and software engineers, to ensure successful project outcomes. Make sure to understand instructions provided in \*.instructions.md files related to the feature. + +When working on implementation-plan artifacts, use these exact paths: + +- `specifications/{task-name}/{task-name}.plan.md` +- `specifications/{task-name}/{task-name}.research.md` +- `specifications/{task-name}/{task-name}.plan-review.md` + +`tsh-plan-reviewer` returns its assessment to you using this exact schema: + +`short summary` + +Derive your next action strictly from the `verdict` and `architect-action-required` attributes, never from the free-text summary. -## Skills Usage Guidelines +After creating, verifying, improving, or updating a plan, you MUST invoke `tsh-plan-reviewer` by default. You may skip review only when you can explicitly state in the handoff back to `tsh-engineering-manager` that the plan meets ALL of these low-risk conditions: -- `tsh-architecture-designing` - to design the overall architecture of the solution, including components, interactions, data flows and to prepare the implementation plan. -- `tsh-codebase-analysing` - to analyze the current codebase and understand the existing architecture, components, and patterns. -- `tsh-implementation-gap-analysing` - to analyze the gap between the current implementation and the proposed solution, ensuring that the plan focuses only on the necessary changes without duplicating existing work. -- `tsh-technical-context-discovering` - to establish project conventions, coding standards, and existing patterns before designing the solution. -- `tsh-sql-and-database-understanding` - when designing database schemas, data models, relationships, indexing strategies, normalisation decisions, and transaction/locking approaches as part of the solution architecture. -- `tsh-designing-multi-cloud-architecture` - when designing cross-provider infrastructure, selecting cloud services, or making build-vs-buy decisions across AWS, Azure, and GCP. -- `tsh-optimizing-cloud-cost` - when evaluating cost implications of architectural decisions, comparing pricing models, or designing cost-efficient infrastructure. -- `tsh-implementing-ci-cd` - when designing CI/CD pipelines, deployment strategies, or delivery workflows as part of the solution architecture. -- `tsh-implementing-terraform-modules` - when designing IaC structure, Terraform module hierarchy, or Terragrunt patterns. -- `tsh-managing-secrets` - when designing secrets management, credential rotation, or vault integration as part of the solution. -- `tsh-implementing-kubernetes` - when designing K8s workload configurations, scaling strategies, Helm chart structure, or cluster topology. -- `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. +1. It is a single phase with very few tasks. +2. It makes no irreversible or high-cost decisions such as database-engine choice, framework or language choice, vendor lock-in, or data-model shape. +3. It includes no schema changes, migrations, or backfills. +4. It introduces no security, authentication, or privacy behavior changes. +5. It introduces no new external dependency and no new architectural pattern. +6. It does not deviate from the research or the established direction. +7. It is confined to one component or concern, such as a copy tweak, one-line config change, or doc-only change. -## Tool Usage Guidelines +If ANY condition above is not met, review is mandatory. -You have access to the `Atlassian` tool. +`specifications/{task-name}/{task-name}.plan-review.md` remains a dialogue artifact that you append to and never overwrite. When `tsh-plan-reviewer` returns `REVISIONS NEEDED`, you address ALL BLOCKER findings without questioning — reviewer BLOCKER findings are non-negotiable in the architect-owned review loop. WARNING and SUGGESTION findings MUST be considered and MAY be rejected only with a justification recorded in `.plan-review.md`. You then revise the plan and re-invoke the reviewer. +Cap the review loop at 3 iterations. If BLOCKER findings remain after the third review iteration, escalate to the user. On `APPROVED`, or when a valid low-risk exemption is explicitly stated, report the finished plan path back to `tsh-engineering-manager`. + +Before finalizing the technical specifications, ensure to review them thoroughly to confirm that all aspects of the solution have been considered and documented clearly. Collaborate with other team members, including context engineers and software engineers, to ensure successful project outcomes. Make sure to understand instructions provided in \*.instructions.md files related to the feature. + + + + +Use these skills as design-time support when shaping or validating an architecture. Start with the core analysis skills, then add the domain-specific ones only when the problem actually touches that concern. + +### Core design-time skills + +- `tsh-architecture-designing` — Use to design the overall solution architecture, major components, interactions, and data flows. +- `tsh-creating-implementation-plans` — MUST use when creating, modifying, or revising an implementation plan; it is the sole owner of plan template, structure, and definition-of-done rules. +- `tsh-codebase-analysing` — Use to analyze the current codebase and understand the existing architecture, components, and patterns before making design decisions. +- `tsh-implementation-gap-analysing` — Use to compare the current implementation with the proposed solution and keep the plan focused on the necessary changes only. +- `tsh-technical-context-discovering` — Use to establish project conventions, coding standards, and established patterns before designing the solution. + +### Conditional domain-specific skills + +- `tsh-sql-and-database-understanding` — Use when the architecture involves database schemas, data models, indexing, relationships, or transaction and locking behavior. +- `tsh-designing-multi-cloud-architecture` — Use when the solution spans multiple cloud providers or requires build-vs-buy decisions across AWS, Azure, or GCP. +- `tsh-optimizing-cloud-cost` — Use when architectural choices must account for pricing, resource sizing, or long-term cloud cost efficiency. +- `tsh-implementing-ci-cd` — Use when the solution architecture includes CI/CD pipelines, delivery workflows, or deployment strategy decisions. +- `tsh-implementing-terraform-modules` — Use when the design covers IaC structure, Terraform module hierarchy, or Terragrunt patterns. +- `tsh-managing-secrets` — Use when the design includes secrets management, credential rotation, or vault integration. +- `tsh-implementing-kubernetes` — Use when the solution architecture includes K8s workload configuration, scaling strategy, Helm charts, or cluster topology. +- `tsh-implementing-observability` — Use when the design includes monitoring architecture, SLOs, alerting, or distributed tracing. +- `tsh-engineering-prompts` — Use when the architecture includes LLM prompt strategy, system prompt design, few-shot vs zero-shot decisions, or prompt versioning. + + + + - **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. + -You have access to the `context7` tool. - + - **MUST use when**: - Evaluating third-party libraries or services by searching their documentation and comparisons. - Verifying compatibility and feature support for specific versions of frameworks or libraries. @@ -106,9 +132,9 @@ You have access to the `context7` tool. - Prioritize official documentation and authoritative sources. Avoid relying on unverified blogs or forums to prevent context pollution. - **SHOULD NOT use for**: - Searching the local codebase (use `search` or `grep_search` instead). + -You have access to the `figma` tool. - + - **MUST use when**: - Designing the component hierarchy and data flow based on UI requirements. - Identifying necessary API endpoints and data structures to support the visual design. @@ -122,9 +148,9 @@ You have access to the `figma` tool. - **SHOULD NOT use for**: - Extracting CSS values or pixel-perfect styling details (leave this for the Software Engineer). - When the task is purely backend with no frontend impact. + -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. @@ -137,9 +163,9 @@ You have access to the `pdf-reader` tool. - **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. + -You have access to the `execute` tool (terminal access). - + - **MUST use when**: - Inspecting project configuration, installed dependencies, or runtime environment details that are not visible from file contents alone. - Running commands to verify infrastructure assumptions (e.g., checking database engine version, available CLI tools, installed SDK versions). @@ -152,9 +178,9 @@ You have access to the `execute` tool (terminal access). - Making changes to the codebase or environment (use `edit` tools instead). - Running or triggering builds, tests, or deployments (e.g., `npm run build`, `mvn test`, `dotnet build`, `terraform apply`). - Long-running or interactive processes. + -You have access to the `sequential-thinking` tool. - + - **MUST use when**: - Designing complex system architectures and component interactions. - Evaluating trade-offs between different technical approaches (e.g., performance vs. maintainability). @@ -166,9 +192,9 @@ You have access to the `sequential-thinking` tool. - **SHOULD NOT use for**: - Simple CRUD operations or standard patterns. - Retrieving basic documentation. + -You have access to the `vscode/askQuestions` tool. - + - **MUST use when**: - Encountering ambiguities in requirements that cannot be resolved from available documentation or codebase. - Needing to confirm trade-off preferences (e.g., performance vs. simplicity) before committing to an architectural decision. @@ -179,3 +205,42 @@ You have access to the `vscode/askQuestions` tool. - **SHOULD NOT use for**: - Questions answerable from the codebase or available documentation. - Implementation details that are the software engineer's responsibility. + + + +- **MUST use when**: inspecting any repository file, instruction, or artifact needed to ground an architectural decision. +- **IMPORTANT**: read the relevant source, plan, or instruction file before making a design judgment. +- **SHOULD NOT use for**: guessing at repository state when a file is available to inspect. + + + +- **MUST use when**: updating plan, research, or review artifacts that this agent owns. +- **IMPORTANT**: keep edits minimal and targeted; use it for documentation artifacts only, not product code. +- **SHOULD NOT use for**: broad refactors or unrelated file changes. + + + +- **MUST use when**: verifying that files, symbols, or repo patterns referenced by the architecture actually exist. +- **IMPORTANT**: use it to ground assumptions in the local codebase before committing to a design. +- **SHOULD NOT use for**: external documentation lookup or broad speculative searching. + + + +- **MUST use when**: invoking `tsh-plan-reviewer` for the architect-owned nested plan review loop. +- **IMPORTANT**: use the `tsh-plan-reviewer` agent to review implementation plans, capture findings, and continue the revise-and-recheck loop. +- **SHOULD NOT use for**: unrelated delegation that does not belong to the plan review handoff. + + + +- **MUST use when**: a narrow VS Code command is the clearest way to inspect workspace state or metadata relevant to the design. +- **IMPORTANT**: keep commands read-only and non-destructive. +- **SHOULD NOT use for**: builds, tests, migrations, or other side-effecting operations. + + + + +- Reviewer BLOCKER findings are non-negotiable inside the architect-owned review loop. +- The review loop is capped at 3 iterations; if BLOCKER findings remain after the third pass, escalate to the user. +- `.plan-review.md` is append-only and must never be overwritten. +- The architect never bypasses mandatory review unless all low-risk exemption conditions are explicitly met. + diff --git a/.github/agents/tsh-engineering-manager.agent.md b/.github/agents/tsh-engineering-manager.agent.md index 05073e0c..4e24c32c 100644 --- a/.github/agents/tsh-engineering-manager.agent.md +++ b/.github/agents/tsh-engineering-manager.agent.md @@ -19,7 +19,6 @@ agents: "tsh-software-engineer", "tsh-devops-engineer", "tsh-architect", - "tsh-plan-reviewer", "tsh-code-reviewer", "tsh-ui-reviewer", "tsh-context-engineer", @@ -91,15 +90,6 @@ When uncertainty remains after your own review, stop, delegate a focused clarifi - Straightforward implementation work whose ownership is already clear and does not require architectural clarification. - -- **MUST delegate to when**: - - A `.plan.md` produced or updated by `tsh-architect` needs validation before implementation proceeds. - - A revised plan needs re-validation after architectural changes. -- **SHOULD NOT delegate to**: - - Requests with no implementation plan to review. - - Plans that are already approved and unchanged since the last review. - - - **MUST delegate to when**: - Implemented changes need review against the plan, feature context, requirements, tests, and acceptance criteria. diff --git a/.github/agents/tsh-plan-reviewer.agent.md b/.github/agents/tsh-plan-reviewer.agent.md index b7f5925f..ff829b4b 100644 --- a/.github/agents/tsh-plan-reviewer.agent.md +++ b/.github/agents/tsh-plan-reviewer.agent.md @@ -1,7 +1,7 @@ --- model: "GPT-5.5" description: "Adversarially challenges architect implementation plans (.plan.md) to find likely failure modes, hidden assumptions, and costly rework risks before coding begins. Returns APPROVED or REVISIONS NEEDED." -tools: ["read", "edit", "search", "sequential-thinking/*", "context7/*", "todo"] +tools: ["read", "edit", "search", "sequential-thinking/*", "context7/*"] user-invocable: false --- @@ -30,11 +30,49 @@ Before starting any task, you check all available skills and decide which one is -- `tsh-architecture-designing` — Use to test whether the proposed shape, phasing, and trade-offs are likely to fail in execution or create rework. -- `tsh-codebase-analysing` — Use during the codebase-reality pass to verify that critical references, dependencies, and abstractions actually exist as assumed. -- `tsh-technical-context-discovering` — Use when repo conventions or established abstractions matter to execution risk, integration fit, or migration safety. -- `tsh-implementation-gap-analysing` — Use to expose gaps between what the plan assumes exists and what actually must be built, migrated, or coordinated. -- `tsh-sql-and-database-understanding` — Use when reviewing schema changes, migrations, backfills, indexing, transaction boundaries, or data compatibility risk. + + +- **MUST use when**: + - Testing whether the proposed shape, phasing, and trade-offs are likely to fail in execution or create rework. +- **SHOULD NOT use for**: + - Redesigning the solution, expanding scope, or imposing stylistic preferences. + + + +- **MUST use when**: + - Verifying the plan follows the owned template, plan structure, and definition-of-done rules. +- **SHOULD NOT use for**: + - Authoring or modifying the plan — the reviewer never edits the plan itself. + + + +- **MUST use when**: + - Running the codebase-reality pass to verify that critical references, dependencies, and abstractions actually exist as the plan assumes. +- **SHOULD NOT use for**: + - Proposing new architecture or refactors outside the review scope. + + + +- **MUST use when**: + - Repo conventions or established abstractions matter to execution risk, integration fit, or migration safety. +- **SHOULD NOT use for**: + - General exploration unrelated to the plan's execution risk. + + + +- **MUST use when**: + - Exposing gaps between what the plan assumes exists and what actually must be built, migrated, or coordinated. +- **SHOULD NOT use for**: + - Adding scope beyond closing the identified gaps. + + + +- **MUST use when**: + - Reviewing schema changes, migrations, backfills, indexing, transaction boundaries, or data compatibility risk. +- **SHOULD NOT use for**: + - Plans with no data-layer or database impact. + + @@ -46,7 +84,7 @@ You MUST actively probe every domain on every review, even when the conclusion i - **Scope gaps and silent omissions** — Requirements from research that the plan does not address, flows that are mentioned but have no tasks, and edge cases acknowledged in research but missing from plan phases. - **Cross-cutting decisions that propagate** — Choices made in Phase 1 that lock in behavior for all subsequent phases: auth model, API contract shape, state management approach, shared code strategy, monorepo vs polyrepo, CI/CD assumptions. - **Build vs buy vs reuse** — Challenge decisions to build from scratch when established libraries exist, or to adopt new dependencies when existing project patterns already solve the problem. - + @@ -62,6 +100,14 @@ You MUST actively probe every domain on every review, even when the conclusion i - If a plan references "modify file X to add method Y", verify file X exists and the proposed modification is compatible. + +- **MUST use when**: + - Persisting the `specifications/{task-name}/{task-name}.plan-review.md` report. + - Appending a new review iteration to the existing `.plan-review.md` dialogue artifact without overwriting prior iterations. +- **SHOULD NOT use for**: + - Modifying the plan under review. + + - **MUST use when**: - Verifying that components, files, functions, or patterns referenced in the plan actually exist. @@ -160,7 +206,7 @@ REVISIONS NEEDED is required when the strongest findings indicate the team is li - You NEVER modify the plan — you only produce review reports. -- You ALWAYS send the review report to `tsh-architect` when the verdict is `REVISIONS NEEDED`. +- You ALWAYS save the review report, then return the structured assessment to your invoker. - You NEVER approve a plan with BLOCKER findings. - You NEVER skip the codebase verification pass — always verify references against actual source. - You NEVER suggest scope expansion — only flag issues within the defined task scope. @@ -178,6 +224,12 @@ REVISIONS NEEDED is required when the strongest findings indicate the team is li Save the final report as `{task-name}.plan-review.md` alongside the plan in the same `specifications` directory. Include a `Decision and Revision History` section on every review iteration, including the first. It is a concise, decision-oriented record of how review pressure shaped the plan, not a transcript. +After saving the report, return this structured assessment to your invoker using this exact schema: + +`short summary` + +`architect-action-required` MUST be `yes` when the verdict is `REVISIONS NEEDED` and `no` when the verdict is `APPROVED`. + `Decision and Revision History` constraints: - Format the section as a compact Markdown table sorted chronologically from oldest to newest. @@ -188,4 +240,4 @@ Save the final report as `{task-name}.plan-review.md` alongside the plan in the - On later iterations, append new rows for new developments or update the relevant existing row concisely so the table stays easy to scan and maintain. - Make reviewer impact explicit: the table must show how the review influenced the plan, not merely that a review occurred. - Do not paste full discussion, exhaustive blocker lists, or long change logs. - + diff --git a/.github/internal-prompts/tsh-plan.prompt.md b/.github/internal-prompts/tsh-plan.prompt.md index 17eb0d74..ce1ada9b 100644 --- a/.github/internal-prompts/tsh-plan.prompt.md +++ b/.github/internal-prompts/tsh-plan.prompt.md @@ -1,12 +1,13 @@ -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 for the provided task or Jira ID and 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. +Use the required skills to understand the feature, design the solution, and author the plan artifact. ## Required Skills Before starting, load and follow these skills: -- `tsh-architecture-designing` - for the architecture design process and output template (`plan.example.md`) +- `tsh-architecture-designing` - for the architecture design process +- `tsh-creating-implementation-plans` - for the plan structure, definition-of-done rules, and output template (`plan.example.md`) - `tsh-codebase-analysing` - for analyzing the existing codebase - `tsh-implementation-gap-analysing` - for verifying what exists vs what needs to be built - `tsh-technical-context-discovering` - for understanding project conventions and patterns @@ -24,25 +25,9 @@ Before starting, load and follow these skills: - Document findings in the "Current Implementation Analysis" section. 4. **Persist technical context**: During steps 2-3, capture all discovered project conventions, coding standards, architecture patterns, tech stack details, testing patterns, and relevant `.instructions.md` rules. Save them in the **"Technical Context"** section of the plan file. This section is critical — downstream implementation agents will read it to avoid redundant codebase analysis. Be thorough: include framework conventions, naming patterns, test commands, linting rules, and any project-specific standards. 5. **Understand project standards**: Review project best practices and quality standards (check `*.instructions.md` files). Incorporate findings into the "Technical Context" section. -6. **Prepare implementation plan**: Create detailed code changes broken down into phases. -7. **Define tasks**: For each phase, identify specific tasks with: - - Clear title - - Description of what the task entails - - Action type: `[CREATE]`, `[MODIFY]`, or `[REUSE]` - - Definition of done as a checkbox list for each task -8. **Address security**: Include security considerations relevant to the implementation. -9. **UI verification tasks**: For features with UI components based on Figma designs, add a `[REUSE]` UI verification task immediately after each implementation task that produces visible UI. The verification task should reference `tsh-ui-reviewer` agent, include the Figma URL, and describe the verify-fix loop (max 5 iterations). Non-visual tasks (data fetching, state management, API integration) do not need verification tasks. -10. **Save the plan**: Follow the `plan.example.md` template from the `tsh-architecture-designing` skill strictly. -11. **Scope control**: Focus ONLY on changes specific to THIS task. Do not include prerequisite work or dependencies - assume those are already done. Do not plan features not in the original requirements (document them separately in an Improvements section). -12. **Avoid duplication**: Never plan to create components, functions, or utilities that already exist. Use the "Current Implementation Analysis" section and plan to reuse or modify existing code. -13. **Bug fixes**: When planning bug fixes, include steps to reproduce the issue, root cause analysis, and implementation of a fix verified by tests. - -Don't provide deployment plans, code pushing instructions, or code review instructions in the repository. - -Follow the template structure and naming conventions strictly to ensure clarity and consistency. +6. **Design the solution architecture using `tsh-architecture-designing`**: Design the solution architecture (components, interactions, data flows, trade-offs) before structuring it into a plan. +7. **Create the implementation plan using `tsh-creating-implementation-plans`**: Delegate ALL plan content to `tsh-creating-implementation-plans`, including task definition, security considerations, UI verification where applicable, the plan save pattern, bug-fix planning, scope control, and duplication avoidance. In case of any ambiguities or missing information for the planning, ask for clarification before finalizing the plan. -Update the plan file after each interaction if new information is gathered. - - + diff --git a/.github/internal-prompts/tsh-review-plan.prompt.md b/.github/internal-prompts/tsh-review-plan.prompt.md index 290cdec6..56c3b3a1 100644 --- a/.github/internal-prompts/tsh-review-plan.prompt.md +++ b/.github/internal-prompts/tsh-review-plan.prompt.md @@ -5,6 +5,7 @@ Stress-test the implementation plan for the provided task. Assume the architect Before starting, load and follow these skills: - `tsh-architecture-designing` - evaluate whether the proposed shape, phasing, and trade-offs are likely to fail in execution or create costly rework +- `tsh-creating-implementation-plans` - verify the plan complies with the owned plan template, structure, and definition-of-done rules - `tsh-codebase-analysing` - verify critical references, dependencies, and abstractions against actual codebase state - `tsh-technical-context-discovering` - check repo conventions or established abstractions only when they materially affect execution risk - `tsh-implementation-gap-analysing` - validate what exists vs what the plan assumes must already be available @@ -68,4 +69,4 @@ The full structured review report is the primary deliverable. Save it as `{task- - **Scope discipline** — never suggest adding features or requirements not in the research file. - **Carry critical issues forward** — unresolved execution-critical issues stay live across iterations until genuinely closed; repeated survival is a reason to escalate, not soften. - + diff --git a/.github/skills/tsh-architecture-designing/SKILL.md b/.github/skills/tsh-architecture-designing/SKILL.md index 0bf5f0b1..ee42baba 100644 --- a/.github/skills/tsh-architecture-designing/SKILL.md +++ b/.github/skills/tsh-architecture-designing/SKILL.md @@ -1,6 +1,6 @@ --- name: tsh-architecture-designing -description: Design the architecture to solve a given task. Propose the solutions to be used to deliver the task following the best practices and standards. +description: "Design the architecture to solve a given task: analyse the codebase, resolve ambiguities, and propose a solution following best practices and standards. Produces the solution design that tsh-creating-implementation-plans turns into an implementation plan." user-invocable: false --- @@ -65,25 +65,14 @@ Don't duplicate any work. Make sure to use `tsh-implementation-gap-analysing` skill to verify what was already implemented from your plan and what should be added. Make sure to include the result in final plan. -Make sure to divide the plan into a small phases.Each phase should have a list of tasks with special place to mark the finished tasks later on. After phase is finished only the fast running tests and quality checks should be run to verify that the implementation is on the right track - unit tests, integration tests, static code analysis, linters, formatting check and project build. +**Step 5: Hand off to plan creation** -The plan has to include code review phase at the end, fully done by `tsh-code-reviewer` agent using [`tsh-review.prompt.md`](../../prompts/tsh-review.prompt.md). Make sure to pass e2e execution to that agent as a part of the prompt and do not run those tests by yourself. - -For features with UI components based on Figma designs, each UI implementation task should be followed by a `[REUSE]` UI verification task delegated to `tsh-ui-reviewer` agent using [`tsh-review-ui.prompt.md`](../../prompts/tsh-review-ui.prompt.md). Include the Figma URL in every verification task. Do not run UI verification from the software engineer level — let the engineering manager orchestrate the verify-fix loop. - -For features involving LLM application prompts (system prompts, RAG templates, tool-calling instructions, classification/extraction prompts), add a `[REUSE]` prompt engineering task delegated to `tsh-prompt-engineer` agent using [`tsh-engineer-prompt.prompt.md`](../../internal-prompts/tsh-engineer-prompt.prompt.md). Separate prompt design from application code — the software engineer implements the integration code, the prompt engineer designs the prompt content. Include the use case, target model, and any existing prompt drafts in the task description. - -Don't provide deployment plans, code pushing instructions, code review instructions on repository. - -**Step 5: Create a implementation plan document** - -Save the plan as a document following the `./plan.example.md` template. - -Don't add or remove any sections from the template. Follow the structure and naming conventions strictly to ensure clarity and consistency. +Turn the designed solution into an implementation plan document using the `tsh-creating-implementation-plans` skill. That skill owns the plan template (`plan.example.md`), the plan structure, and the definition-of-done rules — you MUST load and follow it when authoring the plan. ## Connected Skills - `tsh-codebase-analysing` - for analyzing the existing architecture, components, and patterns - `tsh-implementation-gap-analysing` - for verifying what was already implemented and what should be added - `tsh-technical-context-discovering` - for establishing project conventions and existing patterns before designing +- `tsh-creating-implementation-plans` - for turning the designed solution into a phased implementation plan document - `tsh-sql-and-database-understanding` - for designing database schemas, data models, normalisation strategies, and indexing as part of the solution architecture diff --git a/.github/skills/tsh-creating-agents/SKILL.md b/.github/skills/tsh-creating-agents/SKILL.md index b7c43fce..6a6b0574 100644 --- a/.github/skills/tsh-creating-agents/SKILL.md +++ b/.github/skills/tsh-creating-agents/SKILL.md @@ -144,6 +144,7 @@ Verify the agent file against this checklist: | Section | Required | Purpose | |---|---|---| | `` | **Yes** | Role definition, responsibilities, behavioral guidelines. | +| `` | No | High-level method or philosophy for the agent, typically nested inside ``. | | `` | **Yes** | List of skills the agent uses with guidance for each. | | `` | **Yes** | Tool access rules and usage guidelines per tool. | | `` | No | Domain-specific standards and rules the agent enforces. | @@ -159,7 +160,8 @@ All body content in the agent file must use XML-like tags for structure. Rules: 2. Tags use lowercase-kebab-case naming 3. Nesting is allowed for sub-sections: `` inside `` 4. Markdown formatting (bold, lists, tables, code blocks) is used inside XML tags for content -5. Avoid XML attributes for structural content — use nested tags or Markdown content instead. Exception: identifier attributes (e.g., ``) are acceptable when they improve readability. +5. Justified, agent-specific domain section tags are permitted only when they carry clear meaning not covered by an existing canonical section; they are not arbitrary, and they must still use lowercase-kebab-case with matching opening and closing tags. +6. Avoid XML attributes for structural content — use nested tags or Markdown content instead. Exception: identifier attributes (e.g., ``) are acceptable when they improve readability. Example structure: ```xml diff --git a/.github/skills/tsh-creating-implementation-plans/SKILL.md b/.github/skills/tsh-creating-implementation-plans/SKILL.md new file mode 100644 index 00000000..a54e15d9 --- /dev/null +++ b/.github/skills/tsh-creating-implementation-plans/SKILL.md @@ -0,0 +1,61 @@ +--- +name: tsh-creating-implementation-plans +description: "Creates implementation plan documents (*.plan.md) that break a designed solution into phases and verifiable tasks. Owns the plan template (plan.example.md), plan structure rules, and task definition-of-done rules. Use when authoring, revising, or structuring an implementation plan for any feature or task." +user-invocable: false +--- + +# Creating Implementation Plans + +This skill turns a designed solution into a phased, verifiable implementation plan document. + + + +This skill is the single owner of the plan template (`./plan.example.md`), the plan-structure procedure, and the definition-of-done rules for implementation plans. Other skills and agents MUST reference this skill instead of duplicating plan-structure rules. + + +Every plan defines one Wildly Important Goal, stated explicitly as the single most important outcome the whole plan must achieve. Every phase defines a Goal that clearly advances the Wildly Important Goal, followed by a Description that explains the broader why for reviewers and implementors. The plan itself, after the Wildly Important Goal, also includes a description of the overall approach. + + +The plan must not contain real implementation code. Pseudo-code is allowed only to explain genuinely complicated algorithms or ideas. Diagrams, explanations, and the Technical Context chapter content are allowed and encouraged. + + + +## Plan Creation Process + +Before drafting, read [`./plan.example.md`](./plan.example.md) in full first — it is the canonical structure every plan must follow. Knowing the required sections up front tells you which fields you must research, discover, or design (for example Technical Context, Current Implementation Analysis, and Security Considerations) before you begin, so you gather the right information deliberately rather than backfilling it later. + +1. Confirm inputs: a designed solution, typically from `tsh-architecture-designing`, plus task research and context. Do not design the solution here; this skill structures an already-designed solution into a plan. +2. Define the Wildly Important Goal and the plan description. +3. Divide the work into small phases. Each phase must have a Goal, a Description, and a list of tasks with checkboxes to mark finished tasks later. After each phase is finished, only fast-running tests and quality checks should be run to verify the implementation is on track: unit tests, integration tests, static code analysis, linters, formatting checks, and project build. +4. Define each task. Each task must have a Description, a Definition of Done as a checkbox list, and optional Clues that help the implementor (file paths, line ranges, reference patterns, gotchas). +5. Add the mandatory cross-cutting tasks required by the plan rules. +6. Save the plan as a document following the `./plan.example.md` template. Do not add or remove any sections from the template. Follow the structure and naming conventions strictly. + + +Each task must include a definition of done as a checkbox list. +Definition of done must not include deployment steps. +Definition of done must not include manual QA steps. +Definition of done must not include steps that cannot be verified by a code reviewer during code review. +Example: do not require checking whether tests were failing before the change, because that cannot be verified during code review. + + + +- The plan must include a code review phase at the end, fully done by `tsh-code-reviewer` using [`tsh-review.prompt.md`](../../prompts/tsh-review.prompt.md). Pass e2e execution to that agent as part of the prompt; do not run those tests from the plan author level. +- For features with UI components based on Figma designs, each UI implementation task should be followed by a `[REUSE]` UI verification task delegated to `tsh-ui-reviewer` using [`tsh-review-ui.prompt.md`](../../prompts/tsh-review-ui.prompt.md). Include the Figma URL in every verification task. Do not run UI verification from the software engineer level — let the engineering manager orchestrate the verify-fix loop. +- For features involving LLM application prompts (system prompts, RAG templates, tool-calling instructions, classification/extraction prompts), add a `[REUSE]` prompt engineering task delegated to `tsh-prompt-engineer` using [`tsh-engineer-prompt.prompt.md`](../../internal-prompts/tsh-engineer-prompt.prompt.md). Separate prompt design from application code — the software engineer implements the integration code, the prompt engineer designs the prompt content. Include the use case, target model, and any existing prompt drafts in the task description. +- Do not provide deployment plans, code pushing instructions, or repository code review instructions. + + + +- The plan must capture security considerations relevant to the implementation. +- Save the plan as `specifications/{task-name-or-id}/{task-name}.plan.md`. +- For bug-fix work, the plan must include issue reproduction, root-cause analysis, and a fix verified by tests. +- Plan only the current task. Record prerequisite work, follow-up work, and out-of-scope items in `Improvements` instead of expanding the implementation scope. +- Reuse or modify existing code whenever possible. Consult `Current Implementation Analysis` before planning new components, functions, or utilities. + + +## Connected Skills + +- `tsh-architecture-designing` - designs the solution this skill turns into a plan +- `tsh-implementation-gap-analysing` - verifies what was already implemented before planning new work +- `tsh-technical-context-discovering` - populates the plan's Technical Context section diff --git a/.github/skills/tsh-architecture-designing/plan.example.md b/.github/skills/tsh-creating-implementation-plans/plan.example.md similarity index 68% rename from .github/skills/tsh-architecture-designing/plan.example.md rename to .github/skills/tsh-creating-implementation-plans/plan.example.md index c9e05384..946e4bfc 100644 --- a/.github/skills/tsh-architecture-designing/plan.example.md +++ b/.github/skills/tsh-creating-implementation-plans/plan.example.md @@ -10,12 +10,18 @@ | Priority | | | Related Research | | +## Wildly Important Goal + + + ## Proposed Solution - + +> Note: The plan must not contain real implementation code. Pseudo-code is allowed only for genuinely complicated algorithms or ideas. Diagrams and explanations are encouraged. + ## Current Implementation Analysis ### Already Implemented @@ -82,6 +88,10 @@ Project conventions, coding standards, and patterns discovered during planning. ### Phase 1: +**Goal**: + +**Description**: + #### Task 1.1 - [CREATE/MODIFY/REUSE] **Description**: @@ -91,6 +101,8 @@ Project conventions, coding standards, and patterns discovered during planning. - [ ] - [ ] +**Clues**: + #### Task 1.2 - [CREATE/MODIFY/REUSE] **Description**: @@ -99,8 +111,14 @@ Project conventions, coding standards, and patterns discovered during planning. - [ ] +**Clues**: + ### Phase 2: +**Goal**: + +**Description**: + #### Task 2.1 - [CREATE/MODIFY] **Description**: @@ -112,6 +130,8 @@ Project conventions, coding standards, and patterns discovered during planning. - [ ] - [ ] +**Clues**: + #### Task 2.2 - [REUSE] UI Verification of by `tsh-ui-reviewer` agent **Description**: Run `tsh-ui-reviewer` agent via `tsh-review-ui.prompt.md` to verify against Figma design. Pass the Figma URL and dev server URL. If verification fails, delegate fix to `tsh-software-engineer` and re-verify (max 5 iterations per component). @@ -123,8 +143,14 @@ Project conventions, coding standards, and patterns discovered during planning. - [ ] UI verification passes or escalated to user after 5 iterations - [ ] Verification report documented in Changelog +**Clues**: + ### Phase 3: +**Goal**: + +**Description**: + #### Task 3.1 - [CREATE/MODIFY/REUSE] **Description**: @@ -133,6 +159,26 @@ Project conventions, coding standards, and patterns discovered during planning. - [ ] +**Clues**: + +### Phase 4: Code Review + +**Goal**: + +**Description**: Final verification of the full implementation. This phase is mandatory and always comes last. + +#### Task 4.1 - [REUSE] Code review by `tsh-code-reviewer` agent + +**Description**: Run `tsh-code-reviewer` agent via `tsh-review.prompt.md` to review the complete implementation. Pass e2e test execution to that agent as part of the prompt — do not run e2e tests outside this review. + +**Definition of Done**: + +- [ ] Code review passes with no blocking findings +- [ ] E2e tests executed by the reviewer pass +- [ ] Review outcome documented in Changelog + +**Clues**: + ## Security Considerations - diff --git a/.github/skills/tsh-orchestrating-implementation/SKILL.md b/.github/skills/tsh-orchestrating-implementation/SKILL.md index b2383fbc..cd213857 100644 --- a/.github/skills/tsh-orchestrating-implementation/SKILL.md +++ b/.github/skills/tsh-orchestrating-implementation/SKILL.md @@ -30,7 +30,7 @@ Use the checklist below and keep it synchronized with the todo list: Implementation orchestration progress: - [ ] Step 0: Create flow-start todos - [ ] Step 1: Select Quick Flow or Full Flow -- [ ] Step 2: Write the upfront execution plan +- [ ] Step 2: Plan the task order - [ ] Step 3: Run the selected flow - [ ] Step 4: Close validation and review gates ``` @@ -74,14 +74,16 @@ Use the following decision rules before any delegation. Use `vscode/askQuestions` to recommend Quick Flow or Full Flow, give a short reason, and allow the user to override the recommendation. -### Step 2 - Write the upfront execution plan +### Step 2 - Plan the task order -Write the full ordered agent + prompt call sequence before the first delegation. +Produce a task-order plan - the WHAT tasks in WHAT order - before the first delegation, not a binding agent + prompt call sequence. - Do this immediately after flow selection. - In Full Flow, do it again after plan approval and before execution starts. -- The sequence must cover every planned delegation, review, validation checkpoint, and UI verification item. -- Keep the execution plan synchronized with the todo list whenever order or scope changes. +- List every planned task in order, covering each delegation, review, validation checkpoint, and UI verification item. +- Do not bind an agent or prompt to each task here; the agent + prompt per task is implied at execution time by the Execution routing table. +- Share the intended flow on chat with an explicit note that it may change as execution proceeds. +- Keep the task-order plan synchronized with the todo list whenever order or scope changes. ## Quick Flow @@ -107,25 +109,19 @@ Check the current state before creating or executing any plan. | `*.research.md` | It exists for the current task and contains enough context to explain scope, constraints, requirements, and referenced inputs or links | Route to `tsh-context-engineer` with `tsh-research.prompt.md` | | `*.plan.md` | It exists for the current task and contains ordered, actionable tasks that can be delegated | Route to `tsh-architect` with `tsh-plan.prompt.md` | | Technical Context | The plan has a populated `Technical Context` section with conventions, patterns, stack, and testing guidance relevant to implementation | Route to `tsh-architect` with `tsh-review-codebase.prompt.md` | -| Plan approval state | The current plan is already approved and unchanged since approval | Skip re-review | +| Plan approval state | The current plan is already reviewed, approved, and unchanged since approval | Route to `tsh-architect` with `tsh-plan.prompt.md` to return a finished reviewed plan | ### Planning sequence 1. **Check for existing research and plan files** - Inspect current `*.research.md` and `*.plan.md` state first. 2. **Fill missing context when needed** - If research is missing or incomplete, delegate to `tsh-context-engineer` with `tsh-research.prompt.md`. -3. **Create or refresh the plan when needed** - If the plan is missing, stale, or not actionable, delegate to `tsh-architect` with `tsh-plan.prompt.md`. -4. **Review the plan before execution** - Delegate to `tsh-plan-reviewer` with `tsh-review-plan.prompt.md`. -5. **Run the review loop with hard limits:** - - `*.plan-review.md` remains the source of truth. - - If the plan is approved and unchanged, skip re-review. - - If the verdict is revisions needed, send the review back to `tsh-architect` and re-run review. - - Stop after a maximum of 3 plan-review iterations and escalate to the user if blockers remain. -6. **Create execution todos from the plan** - Create todos per plan task, not just per phase. -7. **Capture UI inventory early** - Find every `[REUSE]` UI task and every Figma URL in the plan and research files. -8. **Ask for the dev server URL when UI tasks exist** - If the UI inventory is non-empty, use `vscode/askQuestions` to get the dev server URL before execution starts. -9. **Apply the Technical Context rule** - If the plan already contains populated Technical Context, use it and skip rediscovery; otherwise delegate to `tsh-architect` with `tsh-review-codebase.prompt.md`. -10. **Use a conditional confirmation gate before execution** - Ask for confirmation before moving from planning to execution only when the plan was newly created, materially changed, escalated, or not yet approved for execution in the current thread. -11. **Rewrite the upfront execution plan after approval** - Expand the ordered agent + prompt call sequence from the approved plan before the first implementation task starts. +3. **Create or refresh the reviewed plan when needed** - If the plan is missing, stale, not actionable, or not already reviewed and approved, delegate to `tsh-architect` with `tsh-plan.prompt.md`. The architect owns producing a finished reviewed plan, including any nested `tsh-plan-reviewer` loop and its maximum of 3 review iterations. The plan MUST be authored following the `tsh-creating-implementation-plans` skill — it owns the plan template and structure rules. +4. **Create execution todos from the plan** - Create todos per plan task, not just per phase. +5. **Capture UI inventory early** - Find every `[REUSE]` UI task and every Figma URL in the plan and research files. +6. **Ask for the dev server URL when UI tasks exist** - If the UI inventory is non-empty, use `vscode/askQuestions` to get the dev server URL before execution starts. +7. **Apply the Technical Context rule** - If the plan already contains populated Technical Context, use it and skip rediscovery; otherwise delegate to `tsh-architect` with `tsh-review-codebase.prompt.md`. +8. **Use a conditional confirmation gate before execution** - Ask for confirmation before moving from planning to execution only when the plan was newly created, materially changed, escalated, or not yet approved for execution in the current thread. +9. **Rewrite the task-order plan after approval** - Refresh the ordered task list from the approved plan before the first implementation task starts; the agent + prompt for each task is resolved at execution time by the Execution routing table. ### Execution routing @@ -171,7 +167,7 @@ Keep the workflow traceable to the plan's preserved branches: | --- | --- | | Step 0 flow selection | 1-4 | | Quick Flow delegation and review | 5-8 | -| Full Flow planning, plan review, and context handling | 9-14 | +| Full Flow planning, reviewed-plan handoff, and context handling | 9-14 | | Execution routing and quality gates | 15-26 | | UI verification enforcement loop | 40-44 | @@ -182,3 +178,4 @@ Keep the workflow traceable to the plan's preserved branches: - `tsh-ui-verifying` - provides the verification standard behind the per-item UI review gate. - `tsh-task-analysing` - helps determine whether research context is complete before planning starts. - `tsh-task-quality-reviewing` - complements planning quality by reinforcing explicit gaps, edge cases, and task completeness. +- `tsh-creating-implementation-plans` - owns the plan template and plan-structure rules used in the planning sequence. diff --git a/README.md b/README.md index 0870a53f..8e7ef883 100644 --- a/README.md +++ b/README.md @@ -82,6 +82,7 @@ These are the minimum VS Code user settings this repository expects: "github.copilot.chat.searchSubagent.enabled": true, "chat.experimental.useSkillAdherencePrompt": true, "chat.customAgentInSubagent.enabled": true, + "chat.subagents.allowInvocationsFromSubagents": true, "github.copilot.chat.agentCustomizationSkill.enabled": true } ``` diff --git a/website/docs/agents/architect.md b/website/docs/agents/architect.md index 8ef7bf4a..633e774e 100644 --- a/website/docs/agents/architect.md +++ b/website/docs/agents/architect.md @@ -44,7 +44,8 @@ Each technical specification includes: ## Skills Loaded -- `tsh-architecture-designing` — Solution design, components, data flows, implementation plan creation. +- `tsh-architecture-designing` — Solution design, components, data flows. +- `tsh-creating-implementation-plans` — Implementation plan template, structure, and DoD rules. - `tsh-codebase-analysing` — Analyze current architecture, components, and patterns. - `tsh-implementation-gap-analysing` — Focus the plan on necessary changes without duplicating existing work. - `tsh-technical-context-discovering` — Establish project conventions and patterns before designing. @@ -62,6 +63,6 @@ Each technical specification includes: After creating the plan, the Architect can hand off to: -- **Architect Reviewer** → internal `/tsh-review-plan` validation before implementation -- **Software Engineer** → `/tsh-implement` (standard implementation) -- **Software Engineer** → `/tsh-implement` (frontend implementation with Figma verification via internal UI prompt) +- **Internal plan review loop** → the Architect invokes `tsh-plan-reviewer` as a nested subagent after creating or revising a plan, addresses all BLOCKER findings, and owns the review loop for up to 3 iterations before escalating. +- **Engineering Manager** → `/tsh-implement` (`Start Implementation`) once the plan is approved/finalized +- **DevOps Engineer** → `Start Infrastructure Implementation` for infrastructure work per the architectural plan diff --git a/website/docs/agents/engineering-manager.md b/website/docs/agents/engineering-manager.md index c84da9ff..bad1c1a4 100644 --- a/website/docs/agents/engineering-manager.md +++ b/website/docs/agents/engineering-manager.md @@ -7,7 +7,7 @@ title: Engineering Manager The Engineering Manager is the orchestration seat for implementation delivery. It defines **WHO** does the work — persona, delegation boundaries, ambiguity handling, and tool discipline — and never writes product code itself. The actual workflow mechanics (flow selection, planning readiness, execution routing, and quality gates) live in the `tsh-orchestrating-implementation` skill, not in the agent. -It runs on the lower-tier **GPT-5.4 mini** model, keeping the orchestration seat cost-efficient while high-leverage decisions are escalated to top-tier advisors (Architect and Plan Reviewer). +It runs on the lower-tier **GPT-5.4 mini** model, keeping the orchestration seat cost-efficient while high-leverage decisions are escalated to the **Architect**. ## How to Use @@ -49,7 +49,6 @@ The agent escalates to the **Architect** when: | **E2E Engineer** | End-to-end test design, mocking strategy, or CI-ready test suites | | **DevOps Engineer** | Infrastructure, Terraform, Kubernetes, CI/CD pipelines, or observability | | **Architect** | Architectural guidance, codebase analysis, or a missing/incomplete plan | -| **Plan Reviewer** | Validating a `.plan.md` before implementation, or re-validating after changes | | **Code Reviewer** | Reviewing implemented changes against the plan, tests, and acceptance criteria | | **UI Reviewer** | Verifying implemented UI against Figma, including `[REUSE]` UI verification tasks | | **Context Engineer** | Gathering requirements and context before the Architect can plan | diff --git a/website/docs/agents/plan-reviewer.md b/website/docs/agents/plan-reviewer.md index dd7efdb8..9cf51ecd 100644 --- a/website/docs/agents/plan-reviewer.md +++ b/website/docs/agents/plan-reviewer.md @@ -15,7 +15,7 @@ The Architect Reviewer is an internal sub-agent that stress-tests implementation - Checking that referenced files, functions, classes, integrations, and patterns actually exist in the codebase. - Surfacing hidden assumptions, sequencing traps, dependency order issues, and migration or data risks. - Challenging integration boundaries, rework risk, and false confidence in test coverage. -- Producing a structured approval or revision report for the Engineering Manager. +- Producing a structured approval or revision report for the Architect. ## What It Produces @@ -25,22 +25,22 @@ The Architect Reviewer is an internal sub-agent that stress-tests implementation ## Tool Access | Tool | Usage | -|---|---| +| --- | --- | | Context7 | Verify framework or library assumptions when the plan references them | | Sequential Thinking | Evaluate trade-offs, phase ordering, and over-engineering risk | | File Read/Search | Inspect the plan, research file, instructions, and referenced code | -| Todo | Track review checklist progress | ## Skills Loaded - `tsh-architecture-designing` — Evaluate architectural shape, phase coherence, and trade-offs. +- `tsh-creating-implementation-plans` — Verify plan template, structure, and definition-of-done compliance. - `tsh-codebase-analysing` — Verify plan references against the actual codebase. -- `tsh-technical-context-discovering` — Check project conventions and existing patterns. +- `tsh-technical-context-discovering` — Check pattern consistency against established conventions. - `tsh-implementation-gap-analysing` — Compare what exists with what the plan proposes. - `tsh-sql-and-database-understanding` — When the plan includes database schema, migration, or query changes. ## How It Is Used - It is not invoked directly by users. -- The Engineering Manager runs it through the internal `/tsh-review-plan` prompt after the Architect produces or updates a plan. +- The Architect directly invokes the Plan Reviewer as a nested subagent after creating or revising a plan; the Engineering Manager is not part of the review loop. - If the reviewer returns revisions, the plan goes back to the Architect and is re-reviewed until approved or escalated. diff --git a/website/docs/getting-started/installation.md b/website/docs/getting-started/installation.md index 7d90df6b..cc578ccb 100644 --- a/website/docs/getting-started/installation.md +++ b/website/docs/getting-started/installation.md @@ -39,6 +39,7 @@ You can configure this once at the **user level** and reuse it across all worksp "github.copilot.chat.searchSubagent.enabled": true, "chat.experimental.useSkillAdherencePrompt": true, "chat.customAgentInSubagent.enabled": true, + "chat.subagents.allowInvocationsFromSubagents": true, "github.copilot.chat.agentCustomizationSkill.enabled": true } ``` @@ -59,7 +60,8 @@ If you prefer the UI instead of editing JSON directly: 6. Search for **"chat.customAgentInSubagent.enabled"** and enable it — allows custom agents in subagents. 7. Search for **"github.copilot.chat.searchSubagent.enabled"** and enable it — enables the search subagent for better codebase analysis. 8. Search for **"chat.experimental.useSkillAdherencePrompt"** and enable it — forces Copilot to use Skills more often. -9. Search for **"github.copilot.chat.agentCustomizationSkill.enabled"** and enable it — enables the agent customization skill. +9. Search for **"chat.subagents.allowInvocationsFromSubagents"** and enable it — allows nested subagent invocation for the architect↔reviewer loop. +10. Search for **"github.copilot.chat.agentCustomizationSkill.enabled"** and enable it — enables the agent customization skill. ## Using in Your Projects diff --git a/website/docs/prompts/internal/plan.md b/website/docs/prompts/internal/plan.md index 2d8ed5a4..34ec1f27 100644 --- a/website/docs/prompts/internal/plan.md +++ b/website/docs/prompts/internal/plan.md @@ -28,16 +28,17 @@ The Engineering Manager identifies that no implementation plan exists and delega 2. **Analyzes tech stack** — Identifies domain-specific best practices. 3. **Verifies current implementation** — Searches the codebase for existing components, functions, and utilities related to the feature. 4. **Understands project standards** — Reviews `*.instructions.md` files. -5. **Prepares implementation plan** — Creates detailed phases with code changes. +5. **Prepares implementation plan** — Uses `tsh-creating-implementation-plans` to structure the plan with phases, tasks, and the owned `plan.example.md` template. 6. **Defines tasks** — Each task has a clear title, description, action type (`[CREATE]`/`[MODIFY]`/`[REUSE]`), and definition of done checklist. 7. **Addresses security** — Includes security considerations. 8. **Defines testing** — Guidelines for validation. -10. **Controls scope** — Only plans changes for THIS task; documents improvements separately. -11. **Supports validation** — The Engineering Manager sends the finished plan to the Architect Reviewer via the internal `/tsh-review-plan` prompt before implementation begins. +9. **Controls scope** — Only plans changes for THIS task; documents improvements separately. +10. **Supports validation** — The Engineering Manager sends the finished plan to the Architect Reviewer via the internal `/tsh-review-plan` prompt before implementation begins. ## Skills Loaded -- `tsh-architecture-designing` — Architecture design process and plan template. +- `tsh-architecture-designing` — Architecture design process. +- `tsh-creating-implementation-plans` — Plan template, structure, and definition-of-done rules. - `tsh-codebase-analysing` — Analyze existing codebase. - `tsh-implementation-gap-analysing` — Verify what exists vs what needs to be built. - `tsh-technical-context-discovering` — Understand project conventions and patterns. diff --git a/website/docs/prompts/internal/review-plan.md b/website/docs/prompts/internal/review-plan.md index e71bf2fb..8e0c2499 100644 --- a/website/docs/prompts/internal/review-plan.md +++ b/website/docs/prompts/internal/review-plan.md @@ -33,6 +33,7 @@ The Engineering Manager uses this internal prompt after the Architect creates or ## Skills Loaded - `tsh-architecture-designing` — Evaluate architectural shape, phase coherence, and trade-offs. +- `tsh-creating-implementation-plans` — Verify plan template, structure, and definition-of-done rules. - `tsh-codebase-analysing` — Verify the plan's references against actual codebase state. - `tsh-technical-context-discovering` — Check pattern consistency against established conventions. - `tsh-implementation-gap-analysing` — Validate what exists vs. what the plan proposes to build. diff --git a/website/docs/skills/architecture-design.md b/website/docs/skills/architecture-design.md index 18143aea..a7b2206c 100644 --- a/website/docs/skills/architecture-design.md +++ b/website/docs/skills/architecture-design.md @@ -8,7 +8,7 @@ title: Architecture Design **Folder:** `.github/skills/tsh-architecture-designing/` **Used by:** Architect -Provides a structured 5-step process for designing solution architecture and creating detailed implementation plans. +Provides a structured 5-step process for designing solution architecture. ## Process @@ -30,28 +30,25 @@ Create the architecture following established patterns and principles. ### Step 5: Document the Plan -Produce a structured implementation plan (`plan.example.md` template) with phased, checklist-style tasks. +Hand off to [Creating Implementation Plans](./creating-implementation-plans.md) so the plan can be authored with the owned `plan.example.md` template and plan-structure rules. ## Enforced Patterns | Category | Patterns | -|---|---| +| --- | --- | | **Software Design** | DRY, KISS, DDD, TDD, CQRS, SOLID | | **Architecture** | Hexagonal, Layered, Modular | | **UI/UX** | Atomic Design, WCAG | | **Security** | OWASP TOP10 | -## Plan Requirements +## Implementation Plan Handoff -- Each phase is independently runnable with quality gates. -- Tasks have `[CREATE]`, `[MODIFY]`, or `[REUSE]` action types. -- Every task has a clear definition of done. -- A code review phase is mandatory at the end. -- No deployment plans or manual QA steps. +Implementation plan authoring rules, template ownership, and task definition-of-done constraints live in [Creating Implementation Plans](./creating-implementation-plans.md). ## Connected Skills - `tsh-codebase-analysing` — Understand existing architecture. - `tsh-implementation-gap-analysing` — Focus on necessary changes only. - `tsh-technical-context-discovering` — Establish project conventions. +- `tsh-creating-implementation-plans` — Author the phased implementation plan. - `tsh-sql-and-database-understanding` — Database schema and data model design. diff --git a/website/docs/skills/creating-implementation-plans.md b/website/docs/skills/creating-implementation-plans.md new file mode 100644 index 00000000..d8e0fdcf --- /dev/null +++ b/website/docs/skills/creating-implementation-plans.md @@ -0,0 +1,52 @@ +--- +sidebar_position: 3 +title: Creating Implementation Plans +--- + +# Creating Implementation Plans + +**Folder:** `.github/skills/tsh-creating-implementation-plans/` +**Used by:** Architect via [`tsh-plan.prompt.md`](../prompts/internal/plan.md); consulted by Architect Reviewer via [`tsh-review-plan.prompt.md`](../prompts/internal/review-plan.md) + +Turns a designed solution into a phased, verifiable implementation plan. + +## Process + +### Step 1: Confirm Inputs + +Start from a designed solution, usually produced by `tsh-architecture-designing`, plus task research and any supporting context. Do not redesign the solution here. + +### Step 2: Define the Wildly Important Goal + +State one explicit Wildly Important Goal for the whole plan and add a short description of the overall approach. + +### Step 3: Break the Work into Phases + +Divide the work into small phases. Each phase needs a Goal, a Description, and tasks with checkboxes. Keep the plan testable with fast-running checks such as unit tests, integration tests, static analysis, linters, formatting, and builds. + +### Step 4: Define Each Task + +Give every task a Description, a Definition of Done checklist, and optional Clues such as file paths, line ranges, reference patterns, or gotchas. + +### Step 5: Add Mandatory Cross-Cutting Tasks + +Include the required shared tasks for code review, UI verification, and prompt engineering when those domains apply. + +### Step 6: Save the Plan Using the Template + +Write the plan as a document that follows `plan.example.md` exactly. Do not add or remove sections from the template. + +## Key Rules + +| Area | Rule | +| --- | --- | +| Goal hierarchy | Every plan has one explicit Wildly Important Goal. Every phase has a Goal that advances it, plus a Description. Every task has a Description, a Definition of Done checklist, and optional Clues. | +| Definition of Done | DoD items must not include deployment steps, manual QA, or anything a code reviewer cannot verify during review. | +| No real code | Do not include production implementation code. Use pseudo-code only when a complicated algorithm truly needs it; diagrams and explanatory context are encouraged. | +| Mandatory cross-cutting tasks | End with a code review phase handled by `tsh-code-reviewer`. Add `[REUSE]` UI verification tasks for Figma-based UI via `tsh-ui-reviewer`, and `[REUSE]` prompt engineering tasks for LLM prompts via `tsh-prompt-engineer`. Do not add deployment plans. | + +## Connected Skills + +- `tsh-architecture-designing` — designs the solution this skill turns into a plan +- `tsh-implementation-gap-analysing` — verifies what was already implemented before planning new work +- `tsh-technical-context-discovering` — populates the plan's Technical Context section diff --git a/website/docs/skills/overview.md b/website/docs/skills/overview.md index d32f17b6..e545113f 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 **32 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 @@ -33,7 +33,8 @@ When an agent starts a task, it checks all available skills and decides which on | Skill | Description | Used By | | ------------------------------------------------------------------ | ------------------------------------------------------------- | -------------------------- | -| [tsh-architecture-designing](./architecture-design) | Solution architecture design and implementation plan creation | Architect | +| [tsh-architecture-designing](./architecture-design) | Solution architecture design | Architect | +| [tsh-creating-implementation-plans](./creating-implementation-plans) | Implementation plan template, structure, and DoD rules | Architect, CR | | [tsh-technical-context-discovering](./technical-context-discovery) | Project conventions and pattern discovery | Architect, CR, SE, E2E, CE | | [tsh-implementing-frontend](./frontend-implementation) | UI component patterns, composition, design tokens | Software Engineer | | [tsh-implementing-forms](./implementing-forms) | Form architecture, schema validation, multi-step flows | Software Engineer | @@ -80,6 +81,7 @@ When an agent starts a task, it checks all available skills and decides which on | Skill | BA | CE | Architect | SE | PE | CR | UI Reviewer | E2E | DevOps | Copilot Eng. | | -------------------------------------- | --- | --- | --------- | --- | --- | --- | ----------- | --- | ------ | ------------ | | tsh-architecture-designing | | | ✅ | | | | | | | | +| tsh-creating-implementation-plans | | | ✅ | | | ✅ | | | | | | tsh-code-reviewing | | | | | ✅ | ✅ | | | | | | tsh-codebase-analysing | ✅ | ✅ | ✅ | ✅ | | | | | ✅ | ✅ | | tsh-creating-agents | | | | | | | | | | ✅ |