diff --git a/.github/agents/tsh-engineering-manager.agent.md b/.github/agents/tsh-engineering-manager.agent.md index 97a8e2b1..13cc271e 100644 --- a/.github/agents/tsh-engineering-manager.agent.md +++ b/.github/agents/tsh-engineering-manager.agent.md @@ -1,5 +1,5 @@ --- -model: "GPT-5.4" +model: "GPT-5.4 mini" description: "Agent specializing delegating implementation tasks to specialized agents based on specified requirements and technical designs." tools: [ diff --git a/.github/internal-prompts/tsh-implement-common-task.prompt.md b/.github/internal-prompts/tsh-implement-common-task.prompt.md index 07a3dd38..5b38e530 100644 --- a/.github/internal-prompts/tsh-implement-common-task.prompt.md +++ b/.github/internal-prompts/tsh-implement-common-task.prompt.md @@ -1,34 +1,39 @@ -Your goal is to implement the feature according to the provided implementation plan and feature context. +Implement the delegated task exactly as written. -Thoroughly review the implementation plan and feature context before starting the implementation. Ensure a clear understanding of the requirements and technical designs to deliver effective solutions. +Read the delegated task block in the plan and only the files/resources named in its `Read First` list. Do not reopen the research file or any external spec notes while executing the task. -Use available tools to gather necessary information and document your findings. +Use the task block’s `Preconditions / Dependencies`, `Changes Required`, `Expected Artifacts`, `Definition of Done`, `Verification`, and `Out of Scope / Do NOT` fields to guide the work. Treat the plan as a non-executable guidance artifact: prose, tables, contracts, and clearly labeled pseudocode are illustrative only and must be translated into project-appropriate implementation. -Don't deviate from the implementation plan. Follow it step by step to ensure all requirements are met. +Stay within the task’s exact file scope. If needed information is missing from the task block or its named reading, stop and ask for clarification rather than widening the scope. +Your goal is to implement the delegated task according to the provided implementation plan. -If you need to make changes to the original solution during implementation, wait for a confirmation before proceeding. Also, ensure to document those changes in the specified plan file in Changelog section. This helps maintain clarity and ensures that all modifications are tracked. +Read the delegated task block carefully before starting. Open only the files and resources explicitly named in its `Read First` section, plus the exact file listed in `Files in Scope` when you are ready to edit. Treat that task block as the source of truth for scope, dependencies, required changes, verification, and guardrails. + +Do not reopen the research file or external spec notes while executing the task. If the task block is missing critical information, stop and ask for clarification or request a plan update instead of running a broader research pass. + +Don't deviate from the implementation plan. Follow the delegated task step by step to ensure all requirements are met. + +If you need to make changes to the original solution during implementation, wait for confirmation before proceeding. ## Required Skills -Before starting, load and follow these skills: +Before starting, load and follow these skills when relevant: -- `tsh-technical-context-discovering` - to establish project conventions, coding standards, and existing patterns - `tsh-implementation-gap-analysing` - to verify current state before making changes +- `tsh-technical-context-discovering` - only for gaps not covered by the delegated task block or its `Read First` items - `tsh-sql-and-database-understanding` - when implementing database schemas, migrations, SQL queries, ORM-based data access, or working with transactions and locking -- `tsh-implementing-backend` - when implementing backend API features: REST/GraphQL endpoints, DataGrid filtering/pagination, database handling, JWT authentication, external service adapters, logging, and Docker setup +- any domain-specific implementation skill named by the wrapper prompt or delegated task ## Workflow -1. Review the implementation plan and feature context thoroughly. -2. **Read the "Technical Context" section from the plan file** (`*.plan.md`). This section contains project conventions, coding standards, architecture patterns, tech stack details, testing patterns, and relevant `.instructions.md` rules already discovered during planning. Use it as your primary source of truth — do NOT re-scan the codebase or re-read instruction files for information already captured there. Only perform additional discovery for aspects not covered by the persisted context. -3. Gather a list of commands you will need during implementation: running tests (unit, integration, E2E and others), linters, building the project, running and generating migrations, etc. These may already be documented in the plan's Technical Context section. Run tests and linters **before** starting implementation and **after** completing each phase. -4. Focus only on the implementation plan. Don't implement anything not part of the plan unless explicitly instructed. -5. Don't implement improvements from the plan's improvements section unless explicitly instructed. -6. Start implementing the feature according to the plan, following each task step by step. -7. After completing each task step, update the relevant plan to reflect progress by checking the box for the completed task step. -8. Before making any changes to the original solution during implementation, ask for confirmation. Document those changes in the plan file's Changelog section with timestamps. -9. Before handing over to review, ensure all tasks in the delegated scope have been completed and the feature meets the defined requirements. Update the acceptance criteria checklist after every verified item. +1. Read the delegated task block and the files or resources named in `Read First`. +2. Keep the scope exact. Do not expand the task beyond the single file listed in `Files in Scope`. +3. Run the relevant checks before and after the change when they are available for the scoped work. +4. Implement only what the delegated task requires. +5. After completing the scoped change, update the relevant `Definition of Done` items and any verified `Quality Assurance` items in the plan. +6. Before making any change to the planned solution, ask for confirmation before proceeding. +7. Treat labeled pseudocode, tables, and contracts in the plan as illustrative guidance only. They are not production code and must not be copied verbatim into source files. -Ensure to write clean, efficient, and maintainable code following best practices and coding standards for the project. +Ensure the implementation stays clean, efficient, and maintainable while following the project patterns surfaced by the delegated task and its named reading. - + diff --git a/.github/internal-prompts/tsh-implement-e2e.prompt.md b/.github/internal-prompts/tsh-implement-e2e.prompt.md index be503a29..e27e2360 100644 --- a/.github/internal-prompts/tsh-implement-e2e.prompt.md +++ b/.github/internal-prompts/tsh-implement-e2e.prompt.md @@ -5,7 +5,7 @@ ## Required Skills Before starting, load and follow these skills: -- `tsh-task-analysing` - to determine the input source and gather task requirements +- `tsh-task-analysing` - to determine the input source for the delegated task block - `tsh-technical-context-discovering` - to establish test conventions, existing patterns, and project configuration - `tsh-e2e-testing` - for Page Object patterns, test structure, mocking strategies, verification loop rules, error recovery, and CI readiness checklist @@ -13,14 +13,16 @@ Before starting, load and follow these skills: ## 1. Context -Follow the `tsh-task-analysing` skill's **Step 0 (Determine input source)** to identify whether context comes from research/plan files, a Jira ID, or directly from the prompt message. +Follow the `tsh-task-analysing` skill's **Step 0 (Determine input source)** only to locate the delegated task block, then use that task block and its `Read First` items as the primary source of truth for scope, fixtures, browser state, route details, and other UI-specific facts. Additionally, always: -- **Read the "Technical Context" section from the plan file** (`*.plan.md`) if it exists — it contains project conventions, test patterns, and commands already discovered during planning. Use it as your primary source and skip re-discovery for aspects already covered. -- Check `*.instructions.md` only for aspects **not covered** by the plan's Technical Context +- **Read the delegated task block first** — Read only the files/resources named in its `Read First` list. +- Check `*.instructions.md` only for aspects **not covered** by the task block or its named reading - Analyze `playwright.config.ts` + existing Page Objects - Discover existing test patterns and locator strategies in the codebase +Treat labeled pseudocode, tables, diagrams, and contracts in the task block as illustrative guidance only. They must not be copied as production test code without translating them into the repository's actual patterns. + --- ## 2. Planning @@ -29,7 +31,7 @@ Map acceptance criteria to scenarios: | Acceptance Criterion | Scenario Type | Test Name | |---------------------|---------------|-----------| -| [from plan/prompt] | Happy/Error/Edge | `should [behavior] when [condition]` | +| [from task block] | Happy/Error/Edge | `should [behavior] when [condition]` | Checklist: - [ ] Each criterion → at least one test @@ -57,7 +59,7 @@ Follow the `tsh-e2e-testing` skill for: ### Coverage | Criterion | Test | Status | |-----------|------|--------| -| [from plan/prompt] | [file#test] | ✅/❌ | +| [from task block] | [file#test] | ✅/❌ | Coverage: X/Y (Z%) @@ -75,12 +77,12 @@ Coverage: X/Y (Z%) - NEW: pages/login.page.ts ``` -Update plan (if plan file exists): check acceptance criteria, add files to Change Log. +Update task status (if a status list exists): check acceptance criteria and mark verified QA items complete. --- ## 5. Code Review (automatic) -After completing E2E tests implementation, always run `tsh-code-reviewer` agent to review the E2E tests against best practices and test quality standards. The agent should be executed automatically without user confirmation. Update the changelog section of the plan file to indicate that E2E code review was performed and include a summary of the findings. +After completing E2E tests implementation, always run `tsh-code-reviewer` agent to review the E2E tests against best practices and test quality standards. The agent should be executed automatically without user confirmation. Update task status or verified QA items to indicate that E2E code review was performed and include a summary of the findings. - + diff --git a/.github/internal-prompts/tsh-implement-observability.prompt.md b/.github/internal-prompts/tsh-implement-observability.prompt.md index 52865185..9e9184ec 100644 --- a/.github/internal-prompts/tsh-implement-observability.prompt.md +++ b/.github/internal-prompts/tsh-implement-observability.prompt.md @@ -16,11 +16,13 @@ Before starting, load and follow these skills: Follow the `tsh-technical-context-discovering` skill to identify existing observability setup. Additionally, always: -- **Read the "Technical Context" section from the plan file** (`*.plan.md`) if it exists — it contains project conventions and patterns already discovered during planning. Use it as your primary source and skip re-discovery for aspects already covered. -- Check `*.instructions.md` only for aspects **not covered** by the plan's Technical Context +- **Read the delegated task block first** — Read the delegated task block in the plan and only the files/resources named in its `Read First` list. Use that task block as the primary source of truth for metric names, log fields, trace spans, alert thresholds, and any rollout or verification notes. Do not rely on global plan sections or broader execution-support packages. +- Check `*.instructions.md` only for aspects **not covered** by the task block or its named reading - Analyze existing monitoring configurations (Prometheus, Grafana, CloudWatch, etc.) - Discover existing alerting rules and dashboards +Treat labeled pseudocode, tables, diagrams, and contracts in the task block as illustrative guidance only. They are not production configuration to copy verbatim. + --- ## 2. Implementation @@ -86,4 +88,4 @@ Skip for: adding alerts, creating dashboards, configuring log retention, adding - Infrastructure provisioning → `/tsh-implement-terraform` - CI/CD pipelines → `/tsh-implement-pipeline` - + diff --git a/.github/internal-prompts/tsh-implement-pipeline.prompt.md b/.github/internal-prompts/tsh-implement-pipeline.prompt.md index 9689ec07..334bd32b 100644 --- a/.github/internal-prompts/tsh-implement-pipeline.prompt.md +++ b/.github/internal-prompts/tsh-implement-pipeline.prompt.md @@ -17,11 +17,13 @@ Before starting, load and follow these skills: Follow the `tsh-technical-context-discovering` skill to identify existing CI/CD setup. Additionally, always: -- **Read the "Technical Context" section from the plan file** (`*.plan.md`) if it exists — it contains project conventions and patterns already discovered during planning. Use it as your primary source and skip re-discovery for aspects already covered. -- Check `*.instructions.md` only for aspects **not covered** by the plan's Technical Context +- **Read the delegated task block first** — Read the delegated task block in the plan and only the files/resources named in its `Read First` list. Use that task block as the primary source of truth for branch names, environment names, approval gates, deployment preconditions, and any other pipeline-specific facts. Do not rely on global plan sections or broader execution-support packages. +- Check `*.instructions.md` only for aspects **not covered** by the task block or its named reading - Analyze existing pipeline configurations (GitHub Actions, GitLab CI, Bitbucket, etc.) - Discover branching strategy and deployment targets +Treat labeled pseudocode, tables, diagrams, and contracts in the task block as illustrative guidance only. They are not production pipeline configuration to copy directly. + --- ## 2. Implementation @@ -82,4 +84,4 @@ Skip for: adding test stages, fixing pipeline bugs, updating versions, adding ca - Kubernetes deployment configuration → `/tsh-deploy-kubernetes` - Monitoring and alerting → `/tsh-implement-observability` - + diff --git a/.github/internal-prompts/tsh-implement-terraform.prompt.md b/.github/internal-prompts/tsh-implement-terraform.prompt.md index b03fd4a8..c7aa0919 100644 --- a/.github/internal-prompts/tsh-implement-terraform.prompt.md +++ b/.github/internal-prompts/tsh-implement-terraform.prompt.md @@ -16,11 +16,13 @@ Before starting, load and follow these skills: Follow the `tsh-technical-context-discovering` skill to identify existing Terraform setup. Additionally, always: -- **Read the "Technical Context" section from the plan file** (`*.plan.md`) if it exists — it contains project conventions and patterns already discovered during planning. Use it as your primary source and skip re-discovery for aspects already covered. -- Check `*.instructions.md` only for aspects **not covered** by the plan's Technical Context +- **Read the delegated task block first** — Read the delegated task block in the plan and only the files/resources named in its `Read First` list. Use that task block as the primary source of truth for module names, state backend notes, provider versions, apply preconditions, and other infrastructure-specific facts. Do not rely on global plan sections or broader execution-support packages. +- Check `*.instructions.md` only for aspects **not covered** by the task block or its named reading - Analyze existing Terraform modules and state configuration - Discover environment organization (workspaces, Terragrunt) +Treat labeled pseudocode, tables, diagrams, and contracts in the task block as illustrative guidance only. They are not production Terraform configuration to copy verbatim. + --- ## 2. Implementation @@ -92,4 +94,4 @@ Skip for: adding resources to existing modules, updating versions, fixing bugs, - Kubernetes workload configuration → `/tsh-deploy-kubernetes` - Monitoring infrastructure → `/tsh-implement-observability` - + diff --git a/.github/internal-prompts/tsh-implement-ui.prompt.md b/.github/internal-prompts/tsh-implement-ui.prompt.md index 184bfd4e..2f8e7a54 100644 --- a/.github/internal-prompts/tsh-implement-ui.prompt.md +++ b/.github/internal-prompts/tsh-implement-ui.prompt.md @@ -1,17 +1,16 @@ -Your goal is to implement the UI feature according to the provided implementation plan and feature context, orchestrating iterative verification against Figma designs until the implementation matches within agreed tolerances. +Your goal is to implement the UI feature according to the delegated task block and its `Read First` items, orchestrating iterative verification against Figma designs until the implementation matches within agreed tolerances. -## Design References from Research & Plan +## Design References from the Task Block -Before delegating tasks, open the research file (`*.research.md`) and plan file (`*.plan.md`) to find all Figma URLs: +Use the delegated task block and its `Read First` items as the only source of truth for Figma URLs, component names, and design notes. -- In the **research file**, look for: - - Figma URLs in the `Relevant Links` section. - - Specific component/node links mentioned in `Gathered Information`. -- In the **plan file**, look for: - - Figma URLs and design references in `Task details`. - - A structured "Design References" subsection mapping views/components to Figma URLs or node IDs. +Look in the task block's `Read First` items for: -Use these URLs when delegating to both `tsh-software-engineer` (implementation context) and `tsh-ui-reviewer` (verification target). +- Figma URLs for the component or section being implemented or verified +- Specific component/node links +- Design notes or constraints tied to that task + +Use these facts when delegating to both `tsh-software-engineer` (implementation context) and `tsh-ui-reviewer` (verification target). ### When Figma link is missing @@ -20,33 +19,33 @@ If you cannot find a Figma URL for a component/section that needs verification: 1. **Stop** — do not delegate implementation or verification for that component 2. **Ask the user** to provide the Figma link for the specific section 3. **Wait for the link** before proceeding -4. **Add the link** to the plan file once provided (in `Task details` or `Design References`) +4. If the task block needs updating, request a plan update so the link is captured in the task block Do NOT skip verification or delegate without a Figma reference. ## Workflow -1. **Review the plan** — Review the implementation plan and feature context thoroughly. Identify which tasks are UI implementation tasks (need Figma verification) and which are non-visual tasks. Extract all Figma URLs from the research/plan files. +1. **Read the delegated task block first** — Identify which tasks are UI implementation tasks and which are non-visual tasks from the task block itself. Use the task block's `Read First` items to extract Figma URLs and design notes before delegating anything. -2. **Delegate codebase analysis (if needed)** — Check if the plan file (`*.plan.md`) contains a populated **"Technical Context"** section. If it does, skip this step — the context was already captured during planning. If the section is missing or empty, use `tsh-architect` agent to perform codebase analysis and technical context discovery to establish project conventions, coding standards, architecture patterns, and existing codebase patterns before implementing. +2. **Delegate codebase analysis (if needed)** — Check whether the delegated task block contains enough UI context (component scope, route, state, interaction details, and design notes) to implement safely. If it does, skip this step — the context was already captured in the task block. If the task block is missing critical UI context, use `tsh-architect` agent to perform codebase analysis and technical context discovery to establish project conventions, coding standards, architecture patterns, and existing codebase patterns before implementing. 3. **Confirm dev server URL** — **Use `vscode/askQuestions` now** to ask the user for the dev server URL (e.g., "What URL is the frontend app running at? Is it http://localhost:3000?"). Do not defer this to later — you need the confirmed URL before any verification can start. Do not guess from running processes or port scans — multiple services may run on different ports. Use the confirmed URL for all subsequent verifications in this session. -4. **Delegate UI implementation** — For each UI implementation task, delegate to `tsh-software-engineer` using [tsh-implement-ui-common-task.prompt.md](../internal-prompts/tsh-implement-ui-common-task.prompt.md). Pass the relevant Figma URLs, component context, and plan section. For non-Figma frontend and backend tasks, use [tsh-implement-common-task.prompt.md](../internal-prompts/tsh-implement-common-task.prompt.md). +4. **Delegate UI implementation** — For each UI implementation task, delegate to `tsh-software-engineer` using [tsh-implement-ui-common-task.prompt.md](../internal-prompts/tsh-implement-ui-common-task.prompt.md). Pass the relevant Figma URLs, component context, and the delegated task block's facts from its `Read First` list. Instruct the engineer to use those task-local details as the primary source of truth and to treat any labeled pseudocode, tables, diagrams, or contracts as guidance only, not production code. For non-Figma frontend and backend tasks, use [tsh-implement-common-task.prompt.md](../internal-prompts/tsh-implement-common-task.prompt.md) with the same task-block-first context. 5. **Delegate UI verification** — After each UI implementation task completes, delegate verification to `tsh-ui-reviewer` using `runSubagent` with [tsh-review-ui.prompt.md](tsh-review-ui.prompt.md). Pass: the Figma URL, the user-confirmed dev server URL from step 3, and the component/section name. The ui-reviewer will compare the Figma design against the running implementation and return a structured report. **Note:** You do NOT need `figma` or `playwright` tools yourself — the `tsh-ui-reviewer` agent has them. Just use `runSubagent` to delegate. Never skip verification because these tools aren't in your own tool list. 6. **Handle verification results**: - - If **PASS** → mark the task and its verification step as complete in the plan. Move to the next task. + - If **PASS** → mark the task and its verification step as complete in task status. Move to the next task. - If **FAIL** → delegate fix to `tsh-software-engineer` — pass the **complete** verification report and explicitly instruct the engineer to fix **ALL** listed differences, not just the first one. After the fix, re-delegate verification to `tsh-ui-reviewer`. Repeat up to **5 iterations per component**. - - After 5 failed iterations → **escalate**: list remaining mismatches with the Figma URL, describe what was tried in each iteration, state the suspected root cause, document in the plan's Changelog, and ask the user for guidance. + - After 5 failed iterations → **escalate**: list remaining mismatches with the Figma URL, describe what was tried in each iteration, state the suspected root cause, record the escalation in the completion summary or plan status items, and ask the user for guidance. 7. **Handle confidence levels** from verification reports: - **HIGH** confidence: fix exactly as reported - **MEDIUM** confidence: fix obvious issues, ask user about unclear ones - **LOW** confidence: ask user before making any changes — tool data may be incomplete -8. **Update the plan** — After completing each task step, update the plan to reflect progress (check the box). Note the verification result (PASS, number of iterations, or escalation). +8. **Update task status** — After completing each task step, update task status or plan status items to reflect progress (check the box). Note the verification result (PASS, number of iterations, or escalation). 9. **Run quality checks after each phase** — Run static code analysis, build the project, run unit and integration tests to verify nothing is broken. @@ -82,7 +81,7 @@ Before proceeding from a UI verification step to the next task or to code review 3. Re-delegate to `tsh-ui-reviewer` once the blocker is resolved 4. Only proceed when you have a valid verification report or the user explicitly instructs you to skip -**Never proceed to code review with unverified UI components.** If verification cannot be completed for a component, document it in the plan's Changelog and get explicit user approval before moving to code review. +**Never proceed to code review with unverified UI components.** If verification cannot be completed for a component, document it in the completion summary or plan status items and get explicit user approval before moving to code review. ## Fallback: When `tsh-ui-reviewer` Returns Errors @@ -90,7 +89,7 @@ If `tsh-ui-reviewer` consistently returns LOW confidence or tool errors: 1. Do not continue the loop blindly 2. Ask the user if they can verify manually (open Figma + app side-by-side) -3. Document the issue in the plan's Changelog +3. Document the issue in the completion summary or plan status items 4. Continue with next component or escalate - + diff --git a/.github/internal-prompts/tsh-plan.prompt.md b/.github/internal-prompts/tsh-plan.prompt.md index 17eb0d74..43c0b1a6 100644 --- a/.github/internal-prompts/tsh-plan.prompt.md +++ b/.github/internal-prompts/tsh-plan.prompt.md @@ -1,48 +1,29 @@ -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 and research notes, then author a lean implementation plan that matches `.github/skills/tsh-architecture-designing/plan.example.md`. -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 research file while authoring to understand the rationale and scope, but keep the plan itself task-block self-contained. The finished plan is the execution artifact: each task must stand on its own with exact file scope, and implementors should only need the delegated task block plus its `Read First` items. ## Required Skills Before starting, load and follow these skills: -- `tsh-architecture-designing` - for the architecture design process 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 -- `tsh-sql-and-database-understanding` - when the feature involves database schema design, data model changes, migrations, or query-heavy implementation +- `tsh-architecture-designing` - to follow the canonical lean plan template. +- `tsh-codebase-analysing` - to map existing files, reuse points, and gaps. +- `tsh-implementation-gap-analysing` - to separate what exists from what still needs planning. +- `tsh-technical-context-discovering` - to capture only the project rules needed for the plan. +- `tsh-sql-and-database-understanding` - when the work involves schema, migrations, or query-heavy changes. ## Workflow -1. **Analyze context**: Review the feature context file (`.research.md`) thoroughly to understand the requirements and scope. Cross-check with industry, domain, and company best practices. -2. **Analyze tech stack**: Understand the project's tech stack, industry, and domain to identify best practices for implementation. -3. **Verify current implementation**: Before planning, perform a thorough analysis of the existing codebase: - - Use semantic search to find components, functions, hooks, utilities, or files related to the feature requirements. - - Identify what is already implemented and functional. - - Identify what exists but needs modification or extension. - - Identify what needs to be created from scratch. - - 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. - -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. - - +1. Read the feature context and research file thoroughly. +2. Check the current codebase and project instructions for facts needed to author the plan. +3. Build one task per file with exact scope. Do not bundle multiple files into a single task. +4. Use only the lean task field set: `Files in Scope`, `Read First`, `Preconditions / Dependencies`, `Changes Required`, `Expected Artifacts`, `Definition of Done`, `Verification`, `Out of Scope / Do NOT`. +5. Keep each task block self-contained. Put any required context, guardrails, and file-specific facts inside the task block rather than in global sections. +6. Keep the plan non-executable and code-free. Prose, tables, contracts, and clearly labeled non-executable pseudocode are allowed. +7. Validate the draft against `plan.example.md` and remove stale maximalist wording or instructions that would make implementors reopen research/spec docs during execution. + +The plan must start with `Task Details`, then `Implementation Plan`, then `Quality Assurance`, and phase blocks must include the reusable `Purpose` / `State Before` / `State After` / `Dependencies / Risks` preamble. + +If the task still has unresolved ambiguity after checking the available sources, ask for clarification before finalizing. + + diff --git a/.github/internal-prompts/tsh-review-plan.prompt.md b/.github/internal-prompts/tsh-review-plan.prompt.md index 290cdec6..528362fe 100644 --- a/.github/internal-prompts/tsh-review-plan.prompt.md +++ b/.github/internal-prompts/tsh-review-plan.prompt.md @@ -20,20 +20,24 @@ Before starting, load and follow these skills: 4. **Failure-modes pass** — Find the strongest reasons the plan may fail during implementation or cause major rework. Prioritize substantive risks such as integration mismatches, unsafe migrations, coordination traps, weak rollout strategies, and brittle task breakdowns. -5. **Hidden-assumptions pass** — Identify assumptions that are unproven in this repository. Flag beliefs about files, abstractions, contracts, environment behavior, team coordination, or data shape that the plan depends on but does not verify. +5. **Self-containedness-for-execution pass** — Explicitly evaluate whether a lower-tier implementor can begin execution from a single delegated task block plus its named `Read First` items without reopening the research file or any out-of-plan docs for basic context recovery. Check whether the task block itself provides enough file-bounded scope, exact task / phase order, non-code boundary guidance, terminology, rules, and constraints to start work safely. Flag any task block that points at external research or out-of-plan documentation. -6. **Codebase-reality pass** — For every critical file, component, function, class, abstraction, or dependency the plan relies on: +6. **Hidden-assumptions pass** — Identify assumptions that are unproven in this repository. Flag beliefs about files, abstractions, contracts, environment behavior, team coordination, or data shape that the plan depends on but does not verify. + +7. **Codebase-reality pass** — For every critical file, component, function, class, abstraction, or dependency the plan relies on: - Search the codebase to verify it exists - Read the file to verify it has the expected interface/behavior - Flag any reference that doesn't match reality or is weaker/more constrained than the plan assumes -7. **Sequencing-and-feasibility pass** — Identify order-of-operations traps, risky migrations, rollback gaps, coordination issues, and test or rollout blind spots. Focus on how the plan could break when executed step by step. +8. **Sequencing-and-feasibility pass** — Identify order-of-operations traps, risky migrations, rollback gaps, coordination issues, and test or rollout blind spots. Focus on how the plan could break when executed step by step. Verify that every phase uses the reusable preamble structure (`Purpose`, `State Before`, `State After`, `Dependencies / Risks`) and that the phase sequence is still coherent. + +9. **Execution-critical decision gate** — Before final verdict, explicitly check for unresolved provider, vendor, stack, framework, auth, privacy, security, integration-contract, or migration-prerequisite decisions that sit on the critical path or lock in downstream work. These cannot be waved through as harmless notes. -8. **Execution-critical decision gate** — Before final verdict, explicitly check for unresolved provider, vendor, stack, framework, auth, privacy, security, integration-contract, or migration-prerequisite decisions that sit on the critical path or lock in downstream work. These cannot be waved through as harmless notes. +10. **Decision-and-revision-history handling** — Always build and maintain a `Decision and Revision History` section as a compact chronological Markdown table, ordered from oldest to newest, including on the first review iteration. On iteration 1, capture the initial plan-shaping decisions the reviewer challenged, why they matter, the current architect position, and the current status. On later iterations, read the existing `.plan-review.md` first and update the same table to show what changed since the prior review, whether the reviewer's concerns were resolved, and which issues remain open. Prefer appending new rows for new developments; update an existing row only when that keeps the table clearer and more maintainable. Keep entries as short summaries with phrase-length cells, not prose blocks, transcripts, or exhaustive changelogs. Explicitly classify prior high-signal issues with compact statuses such as `open`, `changed`, `resolved`, `kept`, or `dropped`. If an issue is downgraded or dropped, explain why briefly in the row. Do not reduce challenge intensity because one issue was fixed. The architect fixing one thing does not mean new issues should not be found. -9. **Decision-and-revision-history handling** — Always build and maintain a `Decision and Revision History` section as a compact chronological Markdown table, ordered from oldest to newest, including on the first review iteration. On iteration 1, capture the initial plan-shaping decisions the reviewer challenged, why they matter, the current architect position, and the current status. On later iterations, read the existing `.plan-review.md` first and update the same table to show what changed since the prior review, whether the reviewer's concerns were resolved, and which issues remain open. Prefer appending new rows for new developments; update an existing row only when that keeps the table clearer and more maintainable. Keep entries as short summaries with phrase-length cells, not prose blocks, transcripts, or exhaustive changelogs. Explicitly classify prior high-signal issues with compact statuses such as `open`, `changed`, `resolved`, `kept`, or `dropped`. If an issue is downgraded or dropped, explain why briefly in the row. Do not reduce challenge intensity because one issue was fixed. The architect fixing one thing does not mean new issues should not be found. +11. **Non-code-boundary pass** — Flag plans that include real / production code, copy-paste-ready implementation snippets, or language-specific source fragments presented as authoritative implementation. Allow Mermaid diagrams, tables, contracts, and clearly labeled non-executable pseudocode. -10. **Produce the report and binary verdict** — Save the full failure-oriented review report with final verdict (`APPROVED` or `REVISIONS NEEDED`) as `{task-name}.plan-review.md` in the same specifications directory as the plan. Do not reduce the persisted artifact to a short verdict memo or manager-style synthesis. +12. **Produce the report and binary verdict** — Save the full failure-oriented review report with final verdict (`APPROVED` or `REVISIONS NEEDED`) as `{task-name}.plan-review.md` in the same specifications directory as the plan. Do not reduce the persisted artifact to a short verdict memo or manager-style synthesis. ## Review Requirements @@ -50,6 +54,7 @@ The full structured review report is the primary deliverable. Save it as `{task- - Reviewed plan path, research file path, review date, and verdict (`APPROVED` or `REVISIONS NEEDED`) - Summary counts for blockers, warnings, and suggestions - `Challenge Domains` — One entry per domain with finding or explicit `no issue` note +- `Self-Containedness for Execution` — explicitly report whether the delegated task block and its named `Read First` items are sufficient for lower-tier execution, including file-bounded scope, exact task / phase order, and the non-code boundary, without reopening research or out-of-plan docs - `Decision and Revision History` — Always present, including on the first review. It is concise evidence of reviewer impact on the plan and must preserve the high-signal, non-transcript standard. Format it as a compact Markdown table sorted chronologically from oldest to newest with these columns: `Date`, `Iteration`, `Decision / Topic`, `Problem / Challenge`, `Plan Decision / Change`, `Status`. Keep cells phrase-length where possible, not paragraph prose. Use compact `Status` values such as `open`, `changed`, `resolved`, `kept`, or `dropped`. - `Top Failure Modes` — the strongest reasons this plan may fail or create expensive rework - `Unproven Assumptions` — assumptions the architect must verify or tighten @@ -63,9 +68,11 @@ The full structured review report is the primary deliverable. Save it as `{task- - **Failure orientation** — look first for why the plan may break, stall, or trigger major rework. - **Verify, don't assume** — always search the codebase before flagging phantom references. The architect may have found something you haven't. +- **Execution-ready, not just well-shaped** — reject plans that look structurally complete but still force the implementor to reopen research for vocabulary, rules, or hidden traps. - **Compressed decision history over completeness** — keep the `Decision and Revision History` section concise and decision-oriented on every iteration as a compact chronological table, preserving only the decisions, reviewer challenges, plan changes, and outcomes that still matter for the current verdict. - **Pragmatism over permissiveness** — issues can exist and the verdict can still be `APPROVED`, but not when execution-critical open decisions remain unresolved. In those cases, default to `REVISIONS NEEDED`. - **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. +- **No production code in plans** — treat real / production code in the plan as a substantive review issue; acceptable guidance artifacts are Mermaid diagrams, tables, contracts, and clearly labeled pseudocode. - + diff --git a/.github/skills/tsh-architecture-designing/SKILL.md b/.github/skills/tsh-architecture-designing/SKILL.md index 0bf5f0b1..81b406ce 100644 --- a/.github/skills/tsh-architecture-designing/SKILL.md +++ b/.github/skills/tsh-architecture-designing/SKILL.md @@ -65,7 +65,7 @@ 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. +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. Every phase must include the reusable preamble block with `Purpose`, `State Before`, `State After`, and `Dependencies / Risks`. 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. 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. @@ -77,9 +77,20 @@ Don't provide deployment plans, code pushing instructions, code review instructi **Step 5: Create a implementation plan document** -Save the plan as a document following the `./plan.example.md` template. +Save the plan as a document following the current `./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. +Treat that template as the canonical output contract. The final plan must stay self-contained at task-block level, file-bounded, and non-executable. Each task block must be sufficient for a lower-tier implementor together with its named `Read First` items; do not rely on always-on global sections or external research/spec docs for execution facts. + +Use the plan to carry forward the context that an implementor would otherwise have to rediscover: + +- Define key domain and workflow terminology only where needed in the relevant task block +- Embed the important technical rules inline in the relevant task block instead of relying on file pointers only +- Capture non-obvious failure modes and "do not do this" guidance in the task block instead of global sections +- Structure every task with the lean field set from the template, including `Files in Scope`, `Read First`, `Preconditions / Dependencies`, `Changes Required`, `Expected Artifacts`, `Definition of Done`, `Verification`, and `Out of Scope / Do NOT` + +Plans are guidance artifacts only. Do not include real / production code in them. Use prose, tables, diagrams, contracts, and clearly labeled non-executable pseudocode when illustrative detail is needed. + +Follow the current template structure and naming conventions strictly to ensure clarity, consistency, and reviewability. ## Connected Skills diff --git a/.github/skills/tsh-architecture-designing/plan.example.md b/.github/skills/tsh-architecture-designing/plan.example.md index c9e05384..13701efc 100644 --- a/.github/skills/tsh-architecture-designing/plan.example.md +++ b/.github/skills/tsh-architecture-designing/plan.example.md @@ -1,158 +1,47 @@ -# - Implementation Plan +# Task name - Implementation Plan ## Task Details -| Field | Value | -| ---------------- | ----------------------- | -| Jira ID | | -| Title | | -| Description | | -| Priority | | -| Related Research | | - -## Proposed Solution - - - - - -## Current Implementation Analysis - -### Already Implemented - -List of existing components, functions, utilities that will be reused (with file paths): - -- - `` - - -### To Be Modified - -List of existing code that needs changes or extensions (with file paths and description of changes): - -- - `` - - -### To Be Created - -List of new components, functions, utilities that need to be built from scratch: - -- - - -## Open Questions - -| # | Question | Answer | Status | -| --- | ---------- | -------- | --------------------- | -| 1 | | | ✅ Resolved / ❓ Open | - -## Technical Context - -Project conventions, coding standards, and patterns discovered during planning. Downstream agents MUST read this section instead of re-discovering the same context. - -### Project Instructions - -- - -### Architecture & Patterns - -- -- - -### Tech Stack - -- -- - -### Code Style & Standards - -- -- - -### Testing Patterns - -- -- - -### Database Patterns - -- - -### Additional Context - -- +| Field | Value | +| --- | --- | +| Purpose | Why this plan exists | +| Scope | One task per file; exact file scope only. | +| Contract | Task blocks are self-contained, non-executable, and code-free. | ## Implementation Plan -### Phase 1: - -#### Task 1.1 - [CREATE/MODIFY/REUSE] - -**Description**: - -**Definition of Done**: - -- [ ] -- [ ] - -#### Task 1.2 - [CREATE/MODIFY/REUSE] - -**Description**: - -**Definition of Done**: - -- [ ] - -### Phase 2: - -#### Task 2.1 - [CREATE/MODIFY] - -**Description**: - -**Figma URL**: - -**Definition of Done**: - -- [ ] -- [ ] - -#### 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). - -**Figma URL**: - -**Definition of Done**: - -- [ ] UI verification passes or escalated to user after 5 iterations -- [ ] Verification report documented in Changelog - -### Phase 3: - -#### Task 3.1 - [CREATE/MODIFY/REUSE] - -**Description**: - -**Definition of Done**: - -- [ ] - -## Security Considerations - -- +Plans are guidance artifacts only. They must not contain real / production code. Allowed formats are prose, tables, contracts, and clearly labeled non-executable pseudocode. + +### Phase 1: Phase name + +| Preamble | Details | +| --- | --- | +| Purpose | Why this phase exists and what boundary it establishes | +| State Before | What is true before this phase starts | +| State After | What will be true when this phase is complete | +| Dependencies / Risks | What this phase depends on and what can go wrong if sequencing is wrong | + +#### Task 1.1 - [MODIFY] Task name + +- **Files in Scope**: Single exact file path +- **Read First**: + - File or resource +- **Preconditions / Dependencies**: Facts or prerequisites that must already be true +- **Changes Required**: + - What to change +- **Expected Artifacts**: + - What should exist after the task +- **Definition of Done**: + - [ ] Specific verifiable criterion +- **Verification**: + - How to confirm the change +- **Out of Scope / Do NOT**: + - Explicit exclusions ## Quality Assurance -Acceptance criteria checklist to verify the implementation meets the defined requirements: - -- [ ] -- [ ] -- [ ] - -## Improvements (Out of Scope) - -Potential improvements identified during planning that are not part of the current task: - -- - -## Changelog - -| Date | Change Description | -| ------ | -------------------- | -| | Initial plan created | +- [ ] One task per file; no bundling across files. +- [ ] Every phase includes the `Purpose` / `State Before` / `State After` / `Dependencies / Risks` preamble. +- [ ] Every task uses only the lean field set: `Files in Scope`, `Read First`, `Preconditions / Dependencies`, `Changes Required`, `Expected Artifacts`, `Definition of Done`, `Verification`, `Out of Scope / Do NOT`. +- [ ] No global `Proposed Solution`, `Current Implementation Analysis`, `Open Questions`, `Glossary / Ubiquitous Language`, `Technical Context`, or `Traps and Warnings` sections appear in the default shape. +- [ ] The plan stays non-executable and code-free, with pseudocode only when clearly labeled as non-executable. diff --git a/website/docs/prompts/internal/plan.md b/website/docs/prompts/internal/plan.md index 2d8ed5a4..a9d9544f 100644 --- a/website/docs/prompts/internal/plan.md +++ b/website/docs/prompts/internal/plan.md @@ -3,7 +3,7 @@ sidebar_position: 10 title: /tsh-plan --- -# /tsh-plan +## /tsh-plan :::info Not invoked directly by users. To trigger implementation planning, use [`/tsh-implement`](../public/implement) — the [Engineering Manager](../../agents/engineering-manager) will automatically delegate to the [Architect](../../agents/architect) when a plan is needed. @@ -12,7 +12,7 @@ Not invoked directly by users. To trigger implementation planning, use [`/tsh-im **Agent:** Architect **File:** `.github/internal-prompts/tsh-plan.prompt.md` -Creates a detailed, phased implementation plan from the research context. +Creates a lean, self-contained implementation plan from the research context. ## How It's Triggered @@ -24,16 +24,13 @@ The Engineering Manager identifies that no implementation plan exists and delega ## What It Does -1. **Analyzes context** — Reviews the `.research.md` file and cross-checks with best practices. -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. -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. +1. **Reviews the available context** — Uses the research notes, relevant codebase facts, and project instructions needed to frame the plan. +2. **Scopes the work tightly** — Produces one task per file with exact file scope only. +3. **Keeps tasks self-contained** — Packs each task block with the facts needed to execute it, so implementors do not need to reopen research or spec docs during execution. +4. **Uses the lean plan shape** — Follows the canonical phase preamble and the task field set defined in `plan.example.md`. +5. **Stays guidance-only** — Writes prose, tables, contracts, and clearly labeled non-executable pseudocode only; no production code. +6. **Captures verification and guardrails** — Adds security, verification, and scope notes where the task needs them. +7. **Supports review** — Sends the finished plan to the Architect Reviewer via the internal `/tsh-review-plan` prompt before implementation begins. ## Skills Loaded @@ -45,17 +42,11 @@ The Engineering Manager identifies that no implementation plan exists and delega ## Output -A `.plan.md` file placed in `specifications//`: +A `.plan.md` file placed in `specifications//` with the canonical top-level shape: `Task Details`, `Implementation Plan`, and `Quality Assurance`. -```text -specifications/ - user-authentication/ - user-authentication.research.md - user-authentication.plan.md ← new - user-authentication.plan-review.md ← generated by the Architect Reviewer -``` +The implementation section uses checklist-style phases with the reusable `Purpose` / `State Before` / `State After` / `Dependencies / Risks` preamble. Each task stays scoped to one file and uses only the lean fields from `plan.example.md`: `Files in Scope`, `Read First`, `Preconditions / Dependencies`, `Changes Required`, `Expected Artifacts`, `Definition of Done`, `Verification`, and `Out of Scope / Do NOT`. -The plan includes checklist-style phases, tasks with `[CREATE]`/`[MODIFY]`/`[REUSE]` action types, acceptance criteria, security considerations, and testing guidelines. +Plans remain guidance artifacts only. Keep them code-free and use prose, tables, contracts, or clearly labeled non-executable pseudocode when detail is needed. :::tip Review the plan thoroughly. Confirm scope, phases, and acceptance criteria before starting implementation. diff --git a/website/docs/skills/architecture-design.md b/website/docs/skills/architecture-design.md index 18143aea..aad83fbe 100644 --- a/website/docs/skills/architecture-design.md +++ b/website/docs/skills/architecture-design.md @@ -3,7 +3,7 @@ sidebar_position: 2 title: Architecture Design --- -# Architecture Design +## Architecture Design **Folder:** `.github/skills/tsh-architecture-designing/` **Used by:** Architect @@ -30,12 +30,12 @@ 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. +Produce a structured implementation plan (`plan.example.md` template) with phased, checklist-style tasks that is self-contained for lower-tier execution. ## Enforced Patterns | Category | Patterns | -|---|---| +| --- | --- | | **Software Design** | DRY, KISS, DDD, TDD, CQRS, SOLID | | **Architecture** | Hexagonal, Layered, Modular | | **UI/UX** | Atomic Design, WCAG | @@ -43,9 +43,12 @@ Produce a structured implementation plan (`plan.example.md` template) with phase ## Plan Requirements -- Each phase is independently runnable with quality gates. -- Tasks have `[CREATE]`, `[MODIFY]`, or `[REUSE]` action types. -- Every task has a clear definition of done. +- Each phase is independently runnable and has clear quality gates. +- Every phase includes the reusable `Purpose` / `State Before` / `State After` / `Dependencies / Risks` preamble. +- Every task is scoped to one file with exact file scope only. +- Tasks use the lean field set from the canonical `plan.example.md` template: `Files in Scope`, `Read First`, `Preconditions / Dependencies`, `Changes Required`, `Expected Artifacts`, `Definition of Done`, `Verification`, and `Out of Scope / Do NOT`. +- Plans are guidance artifacts only — no real / production code. Use prose, tables, contracts, and clearly labeled non-executable pseudocode instead. +- The canonical output contract is `.github/skills/tsh-architecture-designing/plan.example.md`. - A code review phase is mandatory at the end. - No deployment plans or manual QA steps.