From 01f550d2ef15b2955d146ebea82c37b41728ca16 Mon Sep 17 00:00:00 2001 From: Igor Wnek Date: Mon, 15 Jun 2026 18:07:15 +0200 Subject: [PATCH 1/5] refactor: harden task-level template fields and skill rules for tsh-creating-implementation-plans --- .../SKILL.md | 5 ++- .../plan.example.md | 42 +++++++++++++++---- 2 files changed, 38 insertions(+), 9 deletions(-) diff --git a/.github/skills/tsh-creating-implementation-plans/SKILL.md b/.github/skills/tsh-creating-implementation-plans/SKILL.md index a54e15d..cbb2d22 100644 --- a/.github/skills/tsh-creating-implementation-plans/SKILL.md +++ b/.github/skills/tsh-creating-implementation-plans/SKILL.md @@ -16,7 +16,7 @@ This skill is the single owner of the plan template (`./plan.example.md`), the p 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. +The plan must not contain real implementation code or full implementation bodies/function logic. Pseudo-code is allowed only to explain genuinely complicated algorithms or ideas, and task-boundary seam artifacts such as type definitions, function signatures, DTOs, interfaces, and API shapes are allowed when they clarify the contract without supplying implementation bodies. Diagrams, explanations, and the Technical Context chapter content are allowed and encouraged. @@ -27,12 +27,13 @@ Before drafting, read [`./plan.example.md`](./plan.example.md) in full first — 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). +4. Define each task. Each task must have a Description, a `**Files:**` field, and a Definition of Done as a checkbox list. The `**Files:**` field must name every file the task will touch and label each one with `create`, `modify`, or `reuse`. If a file was produced or last touched by an earlier task in the same plan, include an inline back-reference such as `(modify — created in Task 1.1)`; if a file is created and consumed within the same task, no back-reference is needed. Tasks may also include an optional `**Stop Rule:**` sentence near `Clues` that tells the implementor to stop, report, and avoid improvising if the task cannot proceed safely or an expected seam is missing; do not turn this into a formal dependency graph or a `Depends on:` field. Optional Clues should still help the implementor with file paths, line ranges, reference patterns, and 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. +Each task's Definition of Done must include at least one runnable command that a reviewer can verify during review, such as `tsc --noEmit` or `npm run test:unit -- `. 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. diff --git a/.github/skills/tsh-creating-implementation-plans/plan.example.md b/.github/skills/tsh-creating-implementation-plans/plan.example.md index 946e4bf..d88d27a 100644 --- a/.github/skills/tsh-creating-implementation-plans/plan.example.md +++ b/.github/skills/tsh-creating-implementation-plans/plan.example.md @@ -20,7 +20,7 @@ -> 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. +> Note: The plan must not contain real implementation code or full implementation bodies/function logic. Pseudo-code is allowed only to explain genuinely complicated algorithms or ideas, and task-boundary seam artifacts such as type definitions, function signatures, DTOs, interfaces, and API shapes are allowed when they clarify the contract without supplying implementation bodies. Diagrams, explanations, and the Technical Context chapter content are allowed and encouraged. ## Current Implementation Analysis @@ -96,10 +96,14 @@ Project conventions, coding standards, and patterns discovered during planning. **Description**: +**Files:** `src/.ts` (create), `src/.types.ts` (reuse) + **Definition of Done**: -- [ ] -- [ ] +- [ ] +- [ ] Run `tsc --noEmit` + +**Stop Rule:** **Clues**: @@ -107,9 +111,14 @@ Project conventions, coding standards, and patterns discovered during planning. **Description**: +**Files:** `src/.ts` (modify — created in Task 1.1), `src/.test.ts` (reuse) + **Definition of Done**: -- [ ] +- [ ] +- [ ] Run `npm run test:unit -- ` + +**Stop Rule:** **Clues**: @@ -123,12 +132,16 @@ Project conventions, coding standards, and patterns discovered during planning. **Description**: +**Files:** `src/components/.tsx` (modify), `src/components/.types.ts` (reuse) + **Figma URL**: **Definition of Done**: -- [ ] -- [ ] +- [ ] +- [ ] Run `npm run test:unit -- ` + +**Stop Rule:** **Clues**: @@ -136,13 +149,18 @@ Project conventions, coding standards, and patterns discovered during planning. **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). +**Files:** `src/components/.tsx` (reuse), `src/components/.test.tsx` (reuse) + **Figma URL**: **Definition of Done**: +- [ ] Run `npm run test:e2e -- ` - [ ] UI verification passes or escalated to user after 5 iterations - [ ] Verification report documented in Changelog +**Stop Rule:** + **Clues**: ### Phase 3: @@ -155,9 +173,14 @@ Project conventions, coding standards, and patterns discovered during planning. **Description**: +**Files:** `src/.ts` (modify — created in Task 1.1), `src/.spec.ts` (reuse) + **Definition of Done**: -- [ ] +- [ ] +- [ ] Run `npm run lint` + +**Stop Rule:** **Clues**: @@ -171,12 +194,17 @@ Project conventions, coding standards, and patterns discovered during planning. **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. +**Files:** `src/.ts` (reuse), `src/.spec.ts` (reuse) + **Definition of Done**: +- [ ] Run `npm run lint` - [ ] Code review passes with no blocking findings - [ ] E2e tests executed by the reviewer pass - [ ] Review outcome documented in Changelog +**Stop Rule:** + **Clues**: ## Security Considerations From ea2171f70065cd87c88b57bdb4cba74a48f494ce Mon Sep 17 00:00:00 2001 From: Igor Wnek Date: Mon, 15 Jun 2026 18:30:32 +0200 Subject: [PATCH 2/5] refactor: harden phase-level and goal-level template fields and skill rules --- .../tsh-creating-implementation-plans/SKILL.md | 6 +++--- .../plan.example.md | 14 ++++++++++++++ 2 files changed, 17 insertions(+), 3 deletions(-) diff --git a/.github/skills/tsh-creating-implementation-plans/SKILL.md b/.github/skills/tsh-creating-implementation-plans/SKILL.md index cbb2d22..cd876b7 100644 --- a/.github/skills/tsh-creating-implementation-plans/SKILL.md +++ b/.github/skills/tsh-creating-implementation-plans/SKILL.md @@ -13,7 +13,7 @@ This skill turns a designed solution into a phased, verifiable implementation pl 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. +Every plan defines one Wildly Important Goal, stated explicitly as the single most important outcome the whole plan must achieve. The Wildly Important Goal section must keep that main goal as one sentence and also include an explicit Success Measure plus a Do NOT touch / do NOT add list to reduce scope creep. 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 or full implementation bodies/function logic. Pseudo-code is allowed only to explain genuinely complicated algorithms or ideas, and task-boundary seam artifacts such as type definitions, function signatures, DTOs, interfaces, and API shapes are allowed when they clarify the contract without supplying implementation bodies. Diagrams, explanations, and the Technical Context chapter content are allowed and encouraged. @@ -26,8 +26,8 @@ Before drafting, read [`./plan.example.md`](./plan.example.md) in full first — 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 `**Files:**` field, and a Definition of Done as a checkbox list. The `**Files:**` field must name every file the task will touch and label each one with `create`, `modify`, or `reuse`. If a file was produced or last touched by an earlier task in the same plan, include an inline back-reference such as `(modify — created in Task 1.1)`; if a file is created and consumed within the same task, no back-reference is needed. Tasks may also include an optional `**Stop Rule:**` sentence near `Clues` that tells the implementor to stop, report, and avoid improvising if the task cannot proceed safely or an expected seam is missing; do not turn this into a formal dependency graph or a `Depends on:` field. Optional Clues should still help the implementor with file paths, line ranges, reference patterns, and gotchas. +3. Divide the work into small phases. Each phase must have a Goal, a Description, a `**Verification:**` field listing the exact fast-running checks to run after the phase completes, and a list of tasks with checkboxes to mark finished tasks later. Keep phase verification reviewer-verifiable and limited to fast checks such as unit tests, integration tests, static code analysis, linters, formatting checks, and project build. +4. Define each task. Each task must have a Description, a `**Files:**` field, and a Definition of Done as a checkbox list. Phase Description states the broader why for reviewers and implementors. Task Description should use a near-imperative form that names the files and the behavior to change. The `**Files:**` field must name every file the task will touch and label each one with `create`, `modify`, or `reuse`. If a file was produced or last touched by an earlier task in the same plan, include an inline back-reference such as `(modify — created in Task 1.1)`; if a file is created and consumed within the same task, no back-reference is needed. Tasks may also include an optional `**Stop Rule:**` sentence near `Clues` that tells the implementor to stop, report, and avoid improvising if the task cannot proceed safely or an expected seam is missing; do not turn this into a formal dependency graph or a `Depends on:` field. Optional Clues should still help the implementor with file paths, line ranges, reference patterns, and 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. diff --git a/.github/skills/tsh-creating-implementation-plans/plan.example.md b/.github/skills/tsh-creating-implementation-plans/plan.example.md index d88d27a..72cf401 100644 --- a/.github/skills/tsh-creating-implementation-plans/plan.example.md +++ b/.github/skills/tsh-creating-implementation-plans/plan.example.md @@ -14,6 +14,10 @@ +**Success Measure**: + +**Do NOT touch / do NOT add**: + ## Proposed Solution @@ -92,6 +96,10 @@ Project conventions, coding standards, and patterns discovered during planning. **Description**: +**Verification:** `tsc --noEmit`; `npm run test:unit -- ` + + + #### Task 1.1 - [CREATE/MODIFY/REUSE] **Description**: @@ -128,6 +136,8 @@ Project conventions, coding standards, and patterns discovered during planning. **Description**: +**Verification:** `npm run test:unit -- `; `npm run lint` + #### Task 2.1 - [CREATE/MODIFY] **Description**: @@ -169,6 +179,8 @@ Project conventions, coding standards, and patterns discovered during planning. **Description**: +**Verification:** `npm run lint`; `npm run build` + #### Task 3.1 - [CREATE/MODIFY/REUSE] **Description**: @@ -190,6 +202,8 @@ Project conventions, coding standards, and patterns discovered during planning. **Description**: Final verification of the full implementation. This phase is mandatory and always comes last. +**Verification:** `npm run lint`; `npm run build` + #### 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. From 1fd4cba7d07d763d187baf579aaee66a42a3147d Mon Sep 17 00:00:00 2001 From: Igor Wnek Date: Tue, 16 Jun 2026 08:46:59 +0200 Subject: [PATCH 3/5] feat: add open-questions dispatch gate when working on plan --- .github/internal-prompts/tsh-review-plan.prompt.md | 3 ++- .github/skills/tsh-creating-implementation-plans/SKILL.md | 3 +++ .github/skills/tsh-orchestrating-implementation/SKILL.md | 1 + 3 files changed, 6 insertions(+), 1 deletion(-) diff --git a/.github/internal-prompts/tsh-review-plan.prompt.md b/.github/internal-prompts/tsh-review-plan.prompt.md index 56c3b3a..ec9d1fc 100644 --- a/.github/internal-prompts/tsh-review-plan.prompt.md +++ b/.github/internal-prompts/tsh-review-plan.prompt.md @@ -15,7 +15,7 @@ Before starting, load and follow these skills: 1. **Read the research file** (`.research.md`) — understand the full set of requirements, acceptance criteria, and constraints that the plan must address. -2. **Read the plan file** (`.plan.md`) — understand the proposed architecture, phases, tasks, and definitions of done. +2. **Read the plan file** (`.plan.md`) — understand the proposed architecture, phases, tasks, and definitions of done. Stop immediately if any row in `## Open Questions` has Status = `❓ Open`; this is a blocker and review cannot proceed until the architect resolves it. 3. **Challenge-domains pass** — Before diving into general failure modes, systematically attack the plan's most consequential decisions using the challenge domains defined in the agent. For each domain, explicitly state whether an issue was found or not. Pay special attention to technology/stack choices that deviate from research context or prior iterations — these are the highest-value challenges. @@ -42,6 +42,7 @@ Before starting, load and follow these skills: - Attribute at least 2-3 findings to the challenge-domains pass when the evidence supports them. - Do not pad the report with cosmetic, wording, or style-only notes. - Do not fall back to generic quality audits or pattern-consistency checks. +- Flag any `❓ Open` item in the plan's `## Open Questions` table as a blocker requiring resolution before approval. - Treat unexplained deviations from research context or prior established direction as likely `BLOCKERS` until justified. diff --git a/.github/skills/tsh-creating-implementation-plans/SKILL.md b/.github/skills/tsh-creating-implementation-plans/SKILL.md index cd876b7..8128a83 100644 --- a/.github/skills/tsh-creating-implementation-plans/SKILL.md +++ b/.github/skills/tsh-creating-implementation-plans/SKILL.md @@ -15,6 +15,9 @@ This skill is the single owner of the plan template (`./plan.example.md`), the p Every plan defines one Wildly Important Goal, stated explicitly as the single most important outcome the whole plan must achieve. The Wildly Important Goal section must keep that main goal as one sentence and also include an explicit Success Measure plus a Do NOT touch / do NOT add list to reduce scope creep. 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. + +Plans must not be dispatched to an implementor while any Open Questions row has Status = ❓ Open; unresolved questions must be routed back to `tsh-architect` before execution. + The plan must not contain real implementation code or full implementation bodies/function logic. Pseudo-code is allowed only to explain genuinely complicated algorithms or ideas, and task-boundary seam artifacts such as type definitions, function signatures, DTOs, interfaces, and API shapes are allowed when they clarify the contract without supplying implementation bodies. Diagrams, explanations, and the Technical Context chapter content are allowed and encouraged. diff --git a/.github/skills/tsh-orchestrating-implementation/SKILL.md b/.github/skills/tsh-orchestrating-implementation/SKILL.md index cd21385..91c9bb9 100644 --- a/.github/skills/tsh-orchestrating-implementation/SKILL.md +++ b/.github/skills/tsh-orchestrating-implementation/SKILL.md @@ -108,6 +108,7 @@ 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` | +| Open questions gate | It exists and contains no `❓ Open` rows in `## Open Questions`, so unresolved questions are not blocking execution readiness | 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 reviewed, approved, and unchanged since approval | Route to `tsh-architect` with `tsh-plan.prompt.md` to return a finished reviewed plan | From aa403b0524bb617ede764495f9cf5956f3ea0f77 Mon Sep 17 00:00:00 2001 From: Igor Wnek Date: Tue, 16 Jun 2026 12:10:31 +0200 Subject: [PATCH 4/5] docs(website): sync documentation to tsh-creating-implementation-plans skill state --- .../docs/skills/creating-implementation-plans.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/website/docs/skills/creating-implementation-plans.md b/website/docs/skills/creating-implementation-plans.md index d8e0fdc..5a3aa77 100644 --- a/website/docs/skills/creating-implementation-plans.md +++ b/website/docs/skills/creating-implementation-plans.md @@ -18,15 +18,15 @@ Start from a designed solution, usually produced by `tsh-architecture-designing` ### 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. +State one explicit Wildly Important Goal for the whole plan as a single sentence, plus an explicit Success Measure and a Do NOT touch / do NOT add list of non-goals to curb scope creep. 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. +Divide the work into small phases. Each phase needs a Goal, a Description, a `**Verification:**` field listing the exact fast-running commands to run after the phase completes, and tasks with checkboxes. Keep phase verification reviewer-verifiable and limited to fast 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. +Give every task a Description, a `**Files:**` field, a Definition of Done checklist, and optional Clues such as file paths, line ranges, reference patterns, or gotchas. The `**Files:**` field names every file the task touches and labels each one `create`, `modify`, or `reuse`. When a file was produced or last touched by an earlier task in the same plan, add an inline back-reference such as `(modify — created in Task 1.1)`. ### Step 5: Add Mandatory Cross-Cutting Tasks @@ -40,9 +40,10 @@ Write the plan as a document that follows `plan.example.md` exactly. Do not add | 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. | +| Goal hierarchy | Every plan has one explicit Wildly Important Goal stated as one sentence, with a Success Measure and a Do NOT touch / do NOT add list. Every phase has a Goal that advances it, a Description, and a `**Verification:**` field. Every task has a Description, a `**Files:**` field, a Definition of Done checklist, and optional Clues. | +| Definition of Done | Each task's DoD must include at least one runnable command a reviewer can verify during review. 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 or full function bodies. Task-boundary seam artifacts (type definitions, function signatures, DTOs, interfaces, API shapes) are allowed when they clarify the contract without supplying implementation bodies. Use pseudo-code only when a complicated algorithm truly needs it; diagrams and explanatory context are encouraged. | +| Open-questions gate | A plan must not be dispatched to an implementor while any `## Open Questions` row has Status `❓ Open`. Unresolved questions route back to `tsh-architect` before execution. | | 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 From 736c552326cfe620083176a4a9081c9804f20c57 Mon Sep 17 00:00:00 2001 From: Igor Wnek Date: Tue, 16 Jun 2026 17:02:37 +0200 Subject: [PATCH 5/5] refactor: verification of the plan implementation basing on current tech stack --- .../SKILL.md | 6 ++- .../plan.example.md | 40 ++++++++++++++----- 2 files changed, 34 insertions(+), 12 deletions(-) diff --git a/.github/skills/tsh-creating-implementation-plans/SKILL.md b/.github/skills/tsh-creating-implementation-plans/SKILL.md index 8128a83..175de13 100644 --- a/.github/skills/tsh-creating-implementation-plans/SKILL.md +++ b/.github/skills/tsh-creating-implementation-plans/SKILL.md @@ -29,14 +29,16 @@ Before drafting, read [`./plan.example.md`](./plan.example.md) in full first — 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, a `**Verification:**` field listing the exact fast-running checks to run after the phase completes, and a list of tasks with checkboxes to mark finished tasks later. Keep phase verification reviewer-verifiable and limited to fast checks such as unit tests, integration tests, static code analysis, linters, formatting checks, and project build. +3. Divide the work into small phases. Each phase must have a Goal, a Description, a `**Verification:**` field listing the exact fast-running checks to run after the phase completes, and a list of tasks with checkboxes to mark finished tasks later. Keep phase verification reviewer-verifiable and limited to fast checks such as unit tests, integration tests, static code analysis, linters, formatting checks, and project build. Source these checks from the plan's Technical Context → Tech Stack / Testing Patterns rather than assuming Node/npm. 4. Define each task. Each task must have a Description, a `**Files:**` field, and a Definition of Done as a checkbox list. Phase Description states the broader why for reviewers and implementors. Task Description should use a near-imperative form that names the files and the behavior to change. The `**Files:**` field must name every file the task will touch and label each one with `create`, `modify`, or `reuse`. If a file was produced or last touched by an earlier task in the same plan, include an inline back-reference such as `(modify — created in Task 1.1)`; if a file is created and consumed within the same task, no back-reference is needed. Tasks may also include an optional `**Stop Rule:**` sentence near `Clues` that tells the implementor to stop, report, and avoid improvising if the task cannot proceed safely or an expected seam is missing; do not turn this into a formal dependency graph or a `Depends on:` field. Optional Clues should still help the implementor with file paths, line ranges, reference patterns, and 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. -Each task's Definition of Done must include at least one runnable command that a reviewer can verify during review, such as `tsc --noEmit` or `npm run test:unit -- `. +Each task's Definition of Done must include at least one objectively reviewer-verifiable check. +When a task changes code, that check must include at least one runnable command taken verbatim from the task's app stack as recorded in Technical Context → Tech Stack / Testing Patterns, matched to the app the task's Files belong to, never assumed from Node/npm (for example `tsc --noEmit` for a Node app, or `uv run pytest ` for a Python app). +For a docs, config, content, or asset task that has no runnable command, the Definition of Done may instead use a deterministic check a reviewer can confirm by inspecting the changed file, such as a grep-style content assertion (for example `docs/.md contains an "## Usage" section`). 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. diff --git a/.github/skills/tsh-creating-implementation-plans/plan.example.md b/.github/skills/tsh-creating-implementation-plans/plan.example.md index 72cf401..aa6e816 100644 --- a/.github/skills/tsh-creating-implementation-plans/plan.example.md +++ b/.github/skills/tsh-creating-implementation-plans/plan.example.md @@ -96,7 +96,12 @@ Project conventions, coding standards, and patterns discovered during planning. **Description**: -**Verification:** `tsc --noEmit`; `npm run test:unit -- ` +**Verification:** + + @@ -109,7 +114,7 @@ Project conventions, coding standards, and patterns discovered during planning. **Definition of Done**: - [ ] -- [ ] Run `tsc --noEmit` +- [ ] Run `` **Stop Rule:** @@ -124,7 +129,22 @@ Project conventions, coding standards, and patterns discovered during planning. **Definition of Done**: - [ ] -- [ ] Run `npm run test:unit -- ` +- [ ] Run `` + +**Stop Rule:** + +**Clues**: + +#### Task 1.3 - [CREATE/MODIFY] + +**Description**: + +**Files:** `docs/.md` (modify) + +**Definition of Done**: + +- [ ] +- [ ] `docs/.md contains an "## Usage" section` _(deterministic reviewer check — a docs-only task has no runnable command)_ **Stop Rule:** @@ -136,7 +156,7 @@ Project conventions, coding standards, and patterns discovered during planning. **Description**: -**Verification:** `npm run test:unit -- `; `npm run lint` +**Verification:** #### Task 2.1 - [CREATE/MODIFY] @@ -149,7 +169,7 @@ Project conventions, coding standards, and patterns discovered during planning. **Definition of Done**: - [ ] -- [ ] Run `npm run test:unit -- ` +- [ ] Run `` **Stop Rule:** @@ -165,7 +185,7 @@ Project conventions, coding standards, and patterns discovered during planning. **Definition of Done**: -- [ ] Run `npm run test:e2e -- ` +- [ ] Run `` - [ ] UI verification passes or escalated to user after 5 iterations - [ ] Verification report documented in Changelog @@ -179,7 +199,7 @@ Project conventions, coding standards, and patterns discovered during planning. **Description**: -**Verification:** `npm run lint`; `npm run build` +**Verification:** #### Task 3.1 - [CREATE/MODIFY/REUSE] @@ -190,7 +210,7 @@ Project conventions, coding standards, and patterns discovered during planning. **Definition of Done**: - [ ] -- [ ] Run `npm run lint` +- [ ] Run `` **Stop Rule:** @@ -202,7 +222,7 @@ Project conventions, coding standards, and patterns discovered during planning. **Description**: Final verification of the full implementation. This phase is mandatory and always comes last. -**Verification:** `npm run lint`; `npm run build` +**Verification:** #### Task 4.1 - [REUSE] Code review by `tsh-code-reviewer` agent @@ -212,7 +232,7 @@ Project conventions, coding standards, and patterns discovered during planning. **Definition of Done**: -- [ ] Run `npm run lint` +- [ ] Run `` - [ ] Code review passes with no blocking findings - [ ] E2e tests executed by the reviewer pass - [ ] Review outcome documented in Changelog