refactor: tighten architect/plan-reviewer contract for lower-tier orchestration

.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.
 </agent>
 
-<agent name="tsh-plan-reviewer">
-- **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.
-</agent>
-
 <agent name="tsh-code-reviewer">
 - **MUST delegate to when**:
   - Implemented changes need review against the plan, feature context, requirements, tests, and acceptance criteria.

.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
 </agent-role>
 
 <skills-usage>
-- `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.
+
+<skill name="tsh-architecture-designing">
+- **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.
+</skill>
+
+<skill name="tsh-creating-implementation-plans">
+- **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.
+</skill>
+
+<skill name="tsh-codebase-analysing">
+- **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.
+</skill>
+
+<skill name="tsh-technical-context-discovering">
+- **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.
+</skill>
+
+<skill name="tsh-implementation-gap-analysing">
+- **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.
+</skill>
+
+<skill name="tsh-sql-and-database-understanding">
+- **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.
+</skill>
+
 </skills-usage>
 
 <challenge-domains>
@@ -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.
-  </challenge-domains>
+</challenge-domains>
 
 <tool-usage>
 
@@ -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.
 </tool>
 
+<tool name="edit">
+- **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.
+</tool>
+
 <tool name="search">
 - **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
 
 <constraints>
 - 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
 <output-format>
 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:
+
+`<plan-review-report verdict="APPROVED | REVISIONS NEEDED" architect-action-required="yes|no" report-file="specifications/{task-name}/{task-name}.plan-review.md">short summary</plan-review-report>`
+
+`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.
-  </output-format>
+</output-format>

.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.
-
-<!-- TSH_COPILOT_COLLECTIONS:prompt:tsh-plan:v1 -->
+<!-- TSH_COPILOT_COLLECTIONS:prompt:tsh-plan:v3 -->

.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.
 
-<!-- TSH_COPILOT_COLLECTIONS:prompt:tsh-review-plan:v1 -->
+<!-- TSH_COPILOT_COLLECTIONS:prompt:tsh-review-plan:v2 -->

.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

.github/skills/tsh-creating-agents/SKILL.md

@@ -144,6 +144,7 @@ Verify the agent file against this checklist:
 | Section | Required | Purpose |
 |---|---|---|
 | `<agent-role>` | **Yes** | Role definition, responsibilities, behavioral guidelines. |
+| `<approach>` | No | High-level method or philosophy for the agent, typically nested inside `<agent-role>`. |
 | `<skills-usage>` | **Yes** | List of skills the agent uses with guidance for each. |
 | `<tool-usage>` | **Yes** | Tool access rules and usage guidelines per tool. |
 | `<domain-standards>` | 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: `<tool>` inside `<tool-usage>`
 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., `<tool name="...">`) 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., `<tool name="...">`) are acceptable when they improve readability.
 
 Example structure:
 ```xml