@leeovery/claude-technical-workflows 2.1.6 → 2.1.8

package/agents/implementation-polish.md

@@ -20,12 +20,11 @@ You receive file paths and context via the orchestrator's prompt:
 3. **Specification path** — What was intended — design decisions and rationale
 4. **Plan file path** — What was built — the full task landscape
 5. **Plan format reading.md path** — How to read tasks from the plan (format-specific adapter)
-6. **Integration context file path** — Accumulated decisions and patterns from every task
-7. **Project skill paths** — Framework conventions
+6. **Project skill paths** — Framework conventions
 
 On **re-invocation after user feedback**, additionally include:
 
-8. **User feedback** — the user's comments on what to change or focus on
+7. **User feedback** — the user's comments on what to change or focus on
 
 ## Hard Rules
 
@@ -50,7 +49,6 @@ Read and absorb the following. Do not write any code or dispatch any agents duri
 3. **Read project skills** — absorb framework conventions
 4. **Read the plan format's reading.md** — understand how to retrieve tasks from the plan
 5. **Read the plan** — follow the reading adapter's instructions to retrieve all completed tasks. Understand the full scope: phases, tasks, acceptance criteria, what was built
-6. **Read the integration context file** — understand patterns, helpers, and conventions from all tasks
 
 → Proceed to **Step 2**.
 
@@ -58,7 +56,7 @@ Read and absorb the following. Do not write any code or dispatch any agents duri
 
 ## Step 2: Identify Implementation Scope
 
-Find all files changed during implementation. Use git history, the plan's task list, and the integration context to build a complete picture of what was touched. Read and understand the full implemented codebase.
+Find all files changed during implementation. Use git history and the plan's task list to build a complete picture of what was touched. Read and understand the full implemented codebase.
 
 Build a definitive list of implementation files. This list is passed to analysis sub-agents in subsequent steps.
 
@@ -133,8 +131,6 @@ Invoke the `implementation-task-executor` agent (`implementation-task-executor.m
 - code-quality.md path
 - Specification path (if available)
 - Project skill paths
-- Plan file path
-- Integration context file path
 
 **STOP.** Do not proceed until the executor has returned its result.
 
@@ -148,7 +144,6 @@ Invoke the `implementation-task-reviewer` agent (`implementation-task-reviewer.m
 - Specification path
 - The same task description used for the executor (including test rules)
 - Project skill paths
-- Integration context file path
 
 **STOP.** Do not proceed until the reviewer has returned its result.
 

package/agents/implementation-task-executor.md

@@ -18,12 +18,10 @@ You receive file paths and context via the orchestrator's prompt:
 3. **Specification path** — For context when rationale is unclear
 4. **Project skill paths** — Relevant `.claude/skills/` paths for framework conventions
 5. **Task content** — Task ID, phase, and all instructional content: goal, implementation steps, acceptance criteria, tests, edge cases, context, notes. This is your scope.
-6. **Plan file path** — The implementation plan, for understanding the overall task landscape and where this task fits
-7. **Integration context file path** (if exists) — Accumulated notes from prior tasks about established patterns, conventions, and decisions
 
 On **re-invocation after review feedback**, you receive all of the above, plus:
-8. **User-approved review notes** — may be the reviewer's original notes, modified by user, or user's own notes
-9. **Specific issues to address**
+6. **User-approved review notes** — may be the reviewer's original notes, modified by user, or user's own notes
+7. **Specific issues to address**
 
 You are stateless — each invocation starts fresh. The full task content is always provided so you can see what was asked, what was done, and what needs fixing.
 
@@ -33,14 +31,10 @@ You are stateless — each invocation starts fresh. The full task content is alw
 2. **Read code-quality.md** — absorb quality standards
 3. **Read project skills** — absorb framework conventions, testing patterns, architecture patterns
 4. **Read specification** (if provided) — understand broader context for this task
-5. **Explore codebase** — you are weaving into an existing canvas, not creating isolated patches:
-   - If an integration context file was provided, read it first — identify helpers, patterns, and conventions you must reuse before writing anything new
-   - Skim the plan file to understand the task landscape — what's been built, what's coming, where your task fits. Use this for awareness, not to build ahead (YAGNI still applies)
+5. **Explore codebase** — understand what exists before writing anything:
    - Read files and tests related to the task's domain
-   - Search for existing helpers, utilities, and abstractions that solve similar problems — reuse, don't duplicate
-   - When creating an interface or API boundary, read BOTH sides: the code that will consume it AND the code that will implement it
-   - Match conventions established in the codebase: error message style, naming patterns, file organisation, type placement
-   - Your code should read as if the same developer wrote the entire codebase
+   - Identify patterns, conventions, and structures you'll need to follow or extend
+   - Check for existing code that the task builds on or integrates with
 6. **Execute TDD cycle** — follow the process in tdd-workflow.md for each acceptance criterion and test case.
 7. **Verify all acceptance criteria met** — every criterion from the task must be satisfied
 8. **Return structured result**
@@ -81,10 +75,7 @@ FILES_CHANGED: {list of files created/modified}
 TESTS_WRITTEN: {list of test files/methods}
 TEST_RESULTS: {all passing | failures — details}
 ISSUES: {any concerns, blockers, or deviations discovered}
-INTEGRATION_NOTES:
-- {3-5 concise bullet points: key patterns, helpers, conventions, interface decisions established by this task. Anchor to concrete file paths where applicable (e.g., "Created `ValidationHelper` in `src/helpers/validation.ts` — use for all input validation"), but high-level observations without a specific file reference are also valuable}
 ```
 
 - If STATUS is `blocked` or `failed`, ISSUES **must** explain why and what decision is needed.
 - If STATUS is `complete`, all acceptance criteria must be met and all tests passing.
-- After completing the task, document what you created or established that future tasks should be aware of in INTEGRATION_NOTES. This is factual — what exists and why — not evaluative.

package/agents/implementation-task-reviewer.md

@@ -18,7 +18,6 @@ You receive via the orchestrator's prompt:
 1. **Specification path** — The validated specification for design decision context
 2. **Task content** — Same task content the executor received: task ID, phase, and all instructional content
 3. **Project skill paths** — Relevant `.claude/skills/` paths for checking framework convention adherence
-4. **Integration context file path** (if exists) — Accumulated notes from prior tasks, for evaluating cohesion with established patterns
 
 ## Your Process
 
@@ -26,7 +25,7 @@ You receive via the orchestrator's prompt:
 2. **Check unstaged changes** — use `git diff` and `git status` to identify files changed by the executor
 3. **Read all changed files** — implementation code and test code
 4. **Read project skills** — understand framework conventions, testing patterns, architecture patterns
-5. **Evaluate all six review dimensions** (see below)
+5. **Evaluate all five review dimensions** (see below)
 
 ## Review Dimensions
 
@@ -63,15 +62,6 @@ Is this a sound design decision? Will it compose well with future tasks?
 - Will this cause problems for subsequent tasks in the phase?
 - Are there structural concerns that should be raised now rather than compounding?
 
-### 6. Codebase Cohesion
-Does the new code integrate well with the existing codebase? If integration context exists from prior tasks, check against established patterns.
-- Is there duplicated logic that should be extracted into a shared helper?
-- Are existing helpers and patterns being reused where applicable?
-- Are naming conventions consistent with existing code?
-- Are error message conventions consistent (casing, wrapping style, prefixes)?
-- Do interfaces use concrete types rather than generic/any types where possible?
-- Are related types co-located with the interfaces or functions they serve?
-
 ## Fix Recommendations (needs-changes only)
 
 When your verdict is `needs-changes`, you must also recommend how to fix each issue. You have full context — the spec, the task, the conventions, and the code — so use it.
@@ -96,7 +86,7 @@ When alternatives exist, explain the tradeoff briefly — don't just list option
 2. **No git writes** — Do not commit or stage. Reading git history and diffs is fine. The orchestrator handles all git writes.
 3. **One task only** — You review exactly one plan task per invocation.
 4. **Independent judgement** — Evaluate the code yourself. Do not trust the executor's self-assessment.
-5. **All six dimensions** — Evaluate spec conformance, acceptance criteria, test adequacy, convention adherence, architectural quality, and codebase cohesion.
+5. **All five dimensions** — Evaluate spec conformance, acceptance criteria, test adequacy, convention adherence, and architectural quality.
 6. **Be specific** — Include file paths and line numbers for every issue. Vague findings are not actionable.
 7. **Proportional** — Prioritize by impact. Don't nitpick style when the architecture is wrong.
 8. **Task scope only** — Only review what's in the task. Don't flag issues outside the task's scope.
@@ -113,7 +103,6 @@ ACCEPTANCE_CRITERIA: {all met | gaps — list}
 TEST_COVERAGE: {adequate | gaps — list}
 CONVENTIONS: {followed | violations — list}
 ARCHITECTURE: {sound | concerns — details}
-CODEBASE_COHESION: {cohesive | concerns — details}
 ISSUES:
 - {specific issue with file:line reference}
   FIX: {recommended approach}
@@ -121,12 +110,9 @@ ISSUES:
   CONFIDENCE: {high | medium | low}
 NOTES:
 - {non-blocking observations}
-COHESION_NOTES:
-- {2-4 concise bullet points: patterns to maintain, conventions confirmed, architectural integration observations}
 ```
 
 - If VERDICT is `approved`, omit ISSUES entirely (or leave empty)
 - If VERDICT is `needs-changes`, ISSUES must contain specific, actionable items with file:line references AND fix recommendations
 - Each issue must include FIX and CONFIDENCE. ALTERNATIVE is optional — include only when genuinely multiple valid approaches exist
 - NOTES are for non-blocking observations — things worth noting but not requiring changes
-- COHESION_NOTES are always included — they capture patterns and conventions observed for future task context

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leeovery/claude-technical-workflows",
-  "version": "2.1.6",
+  "version": "2.1.8",
   "description": "Technical workflow skills & commands for Claude Code",
   "license": "MIT",
   "author": "Lee Overy <me@leeovery.com>",

package/skills/start-research/SKILL.md

@@ -19,7 +19,7 @@ This is **Phase 1** of the six-phase workflow:
 | 5. Implementation | DOING - tests first, then code | |
 | 6. Review | VALIDATING - check work against artifacts | |
 
-**Stay in your lane**: Explore freely. This is the time for broad thinking, feasibility checks, and learning. Don't jump to formal discussions or specifications yet.
+**Stay in your lane**: Explore freely. This is the time for broad thinking, feasibility checks, and learning. Surface options and tradeoffs — don't make decisions. When a topic converges toward a conclusion, that's a signal it's ready for discussion phase, not a cue to start deciding. Park it and move on.
 
 ---
 

package/skills/technical-implementation/SKILL.md

@@ -196,8 +196,6 @@ After creating the file, populate `project_skills` with the paths confirmed in S
 
 Commit: `impl({topic}): start implementation`
 
-Integration context will accumulate in `docs/workflow/implementation/{topic}-context.md` as tasks complete. This file is created automatically during the task loop — no initialisation needed here.
-
 → Proceed to **Step 5**.
 
 ---
@@ -305,4 +303,4 @@ Commit: `impl({topic}): complete implementation`
 - **[task-normalisation.md](references/task-normalisation.md)** — Normalised task shape for agent invocation
 - **[tdd-workflow.md](references/tdd-workflow.md)** — TDD cycle (passed to executor agent)
 - **[code-quality.md](references/code-quality.md)** — Quality standards (passed to executor agent)
-- **Integration context** — `docs/workflow/implementation/{topic}-context.md` — accumulated notes from completed tasks (created during task loop)
+

package/skills/technical-implementation/references/code-quality.md

@@ -37,15 +37,5 @@ Only implement what's in the plan. Ask: "Is this in the plan?"
 - Long parameter lists (4+)
 - Boolean parameters
 
-## Convention Consistency
-
-When adding to an existing codebase, match what's already there:
-- **Error messages**: Match the casing, wrapping style, and prefix patterns in existing code
-- **Naming**: Follow the project's conventions for files, functions, types, and variables
-- **File organisation**: Follow the project's pattern for splitting concerns across files
-- **Helpers**: Search for existing helpers before creating new ones. After creating one, check if existing code could use it too
-- **Types**: Prefer concrete types over generic/any types when the set of possibilities is known. Use structured return types over multiple bare return values for extensibility
-- **Co-location**: Keep related types near the interfaces or functions they serve
-
 ## Project Standards
 Check `.claude/skills/` for project-specific patterns.

package/skills/technical-implementation/references/steps/invoke-executor.md

@@ -17,12 +17,10 @@ This step invokes the `implementation-task-executor` agent (`../../../../agents/
 3. **Specification path**: from the plan's frontmatter (if available)
 4. **Project skill paths**: from `project_skills` in the implementation tracking file
 5. **Task content**: normalised task content (see [task-normalisation.md](../task-normalisation.md))
-6. **Plan file path**: the implementation plan (same path used to read tasks)
-7. **Integration context file** (if exists): `docs/workflow/implementation/{topic}-context.md`
 
 **Re-attempts after review feedback** additionally include:
-8. **User-approved review notes**: verbatim or as modified by the user
-9. **Specific issues to address**: the ISSUES from the review
+6. **User-approved review notes**: verbatim or as modified by the user
+7. **Specific issues to address**: the ISSUES from the review
 
 The executor is stateless — each invocation starts fresh with no memory of previous attempts. Always pass the full task content so the executor can see what was asked, what was done, and what needs fixing.
 
@@ -38,8 +36,6 @@ TASK: {task name}
 SUMMARY: {2-5 lines — commentary, decisions made, anything off-script}
 TEST_RESULTS: {all passing | failures — details only if failures}
 ISSUES: {blockers or deviations — omit if none}
-INTEGRATION_NOTES:
-- {3-5 bullets: patterns, helpers, conventions established — anchor to file paths where applicable}
 ```
 
 - `complete`: all acceptance criteria met, tests passing

package/skills/technical-implementation/references/steps/invoke-polish.md

@@ -17,12 +17,11 @@ This step invokes the `implementation-polish` agent (`../../../../agents/impleme
 3. **Specification path**: from the plan's frontmatter (if available)
 4. **Plan file path**: the implementation plan
 5. **Plan format reading.md**: `../../../technical-planning/references/output-formats/{format}/reading.md` (format from plan frontmatter)
-6. **Integration context file**: `docs/workflow/implementation/{topic}-context.md`
-7. **Project skill paths**: from `project_skills` in the implementation tracking file
+6. **Project skill paths**: from `project_skills` in the implementation tracking file
 
 **Re-invocation after user feedback** additionally includes:
 
-8. **User feedback**: the user's comments on what to change or focus on
+7. **User feedback**: the user's comments on what to change or focus on
 
 The polish agent is stateless — each invocation starts fresh. Always pass all inputs.
 

package/skills/technical-implementation/references/steps/invoke-reviewer.md

@@ -15,7 +15,6 @@ Invoke `implementation-task-reviewer` with:
 1. **Specification path**: same path given to the executor
 2. **Task content**: same normalised task content the executor received
 3. **Project skill paths**: from `project_skills` in the implementation tracking file
-4. **Integration context file** (if exists): `docs/workflow/implementation/{topic}-context.md` — for checking cohesion with established patterns
 
 ---
 
@@ -31,7 +30,6 @@ ACCEPTANCE_CRITERIA: {all met | gaps — list}
 TEST_COVERAGE: {adequate | gaps — list}
 CONVENTIONS: {followed | violations — list}
 ARCHITECTURE: {sound | concerns — details}
-CODEBASE_COHESION: {cohesive | concerns — details}
 ISSUES:
 - {specific issue with file:line reference}
   FIX: {recommended approach}
@@ -39,9 +37,7 @@ ISSUES:
   CONFIDENCE: {high | medium | low}
 NOTES:
 - {non-blocking observations}
-COHESION_NOTES:
-- {2-4 bullets: patterns to maintain, conventions confirmed, integration quality}
 ```
 
-- `approved`: task passes all six review dimensions
+- `approved`: task passes all five review dimensions
 - `needs-changes`: ISSUES contains specific, actionable items with fix recommendations and confidence levels

package/skills/technical-implementation/references/steps/task-loop.md

@@ -169,27 +169,13 @@ Announce the result (one line, no stop):
 
 The tracking file is a derived view for discovery scripts and cross-topic dependency resolution — not a decision-making input during implementation (except `task_gate_mode` and `fix_gate_mode`).
 
-**Append integration context** — extract INTEGRATION_NOTES from the executor's final output and COHESION_NOTES from the reviewer's output. Append both to `docs/workflow/implementation/{topic}-context.md`:
-
-```
-## T{task-id}: {task name}
-
-### Integration (executor)
-{INTEGRATION_NOTES content}
-
-### Cohesion (reviewer)
-{COHESION_NOTES content}
-```
-
-Create the file if it doesn't exist. This is mechanical text extraction and file append — the same as extracting STATUS to route on. Use outputs from the final approved iteration only.
-
 **Commit all changes** in a single commit:
 
 ```
 impl({topic}): T{task-id} — {brief description}
 ```
 
-Code, tests, plan progress, tracking file, and integration context — one commit per approved task.
+Code, tests, plan progress, and tracking file — one commit per approved task.
 
 This is the end of this iteration.
 

package/skills/technical-research/SKILL.md

@@ -65,6 +65,57 @@ Don't constrain yourself. Research goes wherever it needs to go.
 
 **Be honest**: If something seems flawed or risky, say so. Challenge assumptions.
 
+**Explore, don't decide**: Your job is to surface options, tradeoffs, and understanding — not to pick winners. Synthesis is welcome ("the tradeoffs are X, Y, Z"), conclusions are not ("therefore we should do Y"). Decisions belong in the discussion phase.
+
+## Convergence Awareness
+
+Research threads naturally converge. As you explore a topic, options narrow, tradeoffs clarify, and opinions start forming. This is healthy — but it's also a signal.
+
+### Recognizing convergence
+
+Watch for these signs that a thread is moving from exploration toward decision-making:
+
+- "We should..." or "The best approach is..." language (from you or the user)
+- Options narrowing to a clear frontrunner with well-understood tradeoffs
+- The same conclusion being reached from multiple angles
+- Discussion shifting from "what are the options?" to "which option?"
+- You or the user starting to advocate for a particular approach
+
+### What to do
+
+When you notice convergence, **flag it and give the user options**:
+
+> "This thread seems to be converging — we've explored {topic} enough that the tradeoffs are clear and it's approaching decision territory.
+>
+> - **`p`/`park`** — Mark as discussion-ready and move to another topic
+> - **`k`/`keep`** — Keep digging, there's more to understand
+> - **`s`/`something else`** — Your call"
+
+**Never decide for the user.** Even if the answer seems obvious, flag it and ask.
+
+### If the user parks it
+
+Document the convergence point in the research file using this marker:
+
+```markdown
+> **Discussion-ready**: {Brief summary of what was explored and why it's ready for decision-making. Key tradeoffs or options identified.}
+```
+
+Then continue with whatever's next — another topic, a different angle, or wrapping up the session.
+
+### If the user keeps digging
+
+Continue exploring. The convergence signal isn't a stop sign — it's an awareness check. The user might want to stress-test the emerging conclusion, explore edge cases, or understand the problem more deeply before moving on. That's valid research work.
+
+### Synthesis vs decision
+
+This distinction matters:
+
+- **Synthesis** (research): "There are three viable approaches. A is simplest but limited. B scales better but costs more. C is future-proof but complex."
+- **Decision** (discussion): "We should go with B because scaling matters more than simplicity for this project."
+
+Synthesis is your job. Decisions are not. Present the landscape, don't pick the destination.
+
 ## Questioning
 
 For structured questioning, use the interview reference (`references/interview.md`). Good research questions: