@leeovery/claude-technical-workflows 2.1.15 → 2.1.17

package/agents/implementation-analysis-architecture.md

@@ -18,6 +18,7 @@ You receive via the orchestrator's prompt:
 3. **Project skill paths** — relevant `.claude/skills/` paths for framework conventions
 4. **code-quality.md path** — quality standards
 5. **Topic name** — the implementation topic
+6. **Cycle number** — which analysis cycle this is (used in output file naming)
 
 ## Your Focus
 
@@ -26,6 +27,8 @@ You receive via the orchestrator's prompt:
 - Integration test gaps — are cross-task workflows tested end-to-end?
 - Seam quality between task boundaries — do the pieces fit together cleanly?
 - Over/under-engineering — are abstractions justified by usage? Is raw code crying out for structure?
+- Missed composition opportunities — are new abstractions independently implemented when they could be derived from existing ones? If two queries are logical inverses, one should be defined in terms of the other.
+- Type safety at boundaries — are interfaces or function signatures using untyped parameters when the concrete types are known? Runtime type checks inside implementations signal the signature should be more specific.
 
 ## Your Process
 
@@ -34,7 +37,7 @@ You receive via the orchestrator's prompt:
 3. **Read specification** — understand design intent and boundaries
 4. **Read all implementation files** — understand the full picture
 5. **Analyze architecture** — evaluate how the pieces compose as a whole
-6. **Write findings** to `docs/workflow/implementation/{topic}/analysis-architecture.md`
+6. **Write findings** to `docs/workflow/implementation/{topic}/analysis-architecture-c{cycle-number}.md`
 
 ## Hard Rules
 
@@ -48,7 +51,7 @@ You receive via the orchestrator's prompt:
 
 ## Output File Format
 
-Write to `docs/workflow/implementation/{topic}/analysis-architecture.md`:
+Write to `docs/workflow/implementation/{topic}/analysis-architecture-c{cycle-number}.md`:
 
 ```
 AGENT: architecture

package/agents/implementation-analysis-duplication.md

@@ -18,6 +18,7 @@ You receive via the orchestrator's prompt:
 3. **Project skill paths** — relevant `.claude/skills/` paths for framework conventions
 4. **code-quality.md path** — quality standards
 5. **Topic name** — the implementation topic
+6. **Cycle number** — which analysis cycle this is (used in output file naming)
 
 ## Your Focus
 
@@ -33,7 +34,7 @@ You receive via the orchestrator's prompt:
 3. **Read specification** — understand design intent
 4. **Read all implementation files** — build a mental map of the full codebase
 5. **Analyze for duplication** — compare patterns across files, identify extraction candidates
-6. **Write findings** to `docs/workflow/implementation/{topic}/analysis-duplication.md`
+6. **Write findings** to `docs/workflow/implementation/{topic}/analysis-duplication-c{cycle-number}.md`
 
 ## Hard Rules
 
@@ -47,7 +48,7 @@ You receive via the orchestrator's prompt:
 
 ## Output File Format
 
-Write to `docs/workflow/implementation/{topic}/analysis-duplication.md`:
+Write to `docs/workflow/implementation/{topic}/analysis-duplication-c{cycle-number}.md`:
 
 ```
 AGENT: duplication

package/agents/implementation-analysis-standards.md

@@ -18,6 +18,7 @@ You receive via the orchestrator's prompt:
 3. **Project skill paths** — relevant `.claude/skills/` paths for framework conventions
 4. **code-quality.md path** — quality standards
 5. **Topic name** — the implementation topic
+6. **Cycle number** — which analysis cycle this is (used in output file naming)
 
 ## Your Focus
 
@@ -33,7 +34,7 @@ You receive via the orchestrator's prompt:
 3. **Read code-quality.md** — understand quality standards
 4. **Read all implementation files** — map each file back to its spec requirements
 5. **Compare implementation against spec** — check every decision point
-6. **Write findings** to `docs/workflow/implementation/{topic}/analysis-standards.md`
+6. **Write findings** to `docs/workflow/implementation/{topic}/analysis-standards-c{cycle-number}.md`
 
 ## Hard Rules
 
@@ -47,7 +48,7 @@ You receive via the orchestrator's prompt:
 
 ## Output File Format
 
-Write to `docs/workflow/implementation/{topic}/analysis-standards.md`:
+Write to `docs/workflow/implementation/{topic}/analysis-standards-c{cycle-number}.md`:
 
 ```
 AGENT: standards

package/agents/implementation-analysis-synthesizer.md

@@ -20,13 +20,13 @@ You receive via the orchestrator's prompt:
 
 ## Your Process
 
-1. **Read all findings files** from `docs/workflow/implementation/{topic}/` — look for `analysis-duplication.md`, `analysis-standards.md`, and `analysis-architecture.md`
+1. **Read all findings files** from `docs/workflow/implementation/{topic}/` — look for `analysis-duplication-c{cycle-number}.md`, `analysis-standards-c{cycle-number}.md`, and `analysis-architecture-c{cycle-number}.md`
 2. **Deduplicate** — same issue found by multiple agents → one finding, note all sources
 3. **Group related findings** — multiple findings about the same pattern become one task (e.g., 3 duplication findings about the same helper pattern = 1 "extract helper" task)
 4. **Filter** — discard low-severity findings unless they cluster into a pattern. Never discard high-severity.
 5. **Normalize** — convert each group into a task using the canonical task template (Problem / Solution / Outcome / Do / Acceptance Criteria / Tests)
-6. **Write report** — output to `docs/workflow/implementation/{topic}/analysis-report.md`
-7. **Write staging file** — if actionable tasks exist, write to `docs/workflow/implementation/{topic}/analysis-tasks.md` with `status: pending` for each task
+6. **Write report** — output to `docs/workflow/implementation/{topic}/analysis-report-c{cycle-number}.md`
+7. **Write staging file** — if actionable tasks exist, write to `docs/workflow/implementation/{topic}/analysis-tasks-c{cycle-number}.md` with `status: pending` for each task
 
 ## Report Format
 

package/agents/implementation-task-reviewer.md

@@ -42,10 +42,12 @@ Are all criteria genuinely met — not just self-reported?
 - Check for criteria that are technically met but miss the intent
 
 ### 3. Test Adequacy
-Do tests actually verify the criteria? Are edge cases covered?
+Do tests actually verify the criteria? Are assertions precise? Are edge cases covered?
 - Is there a test for each acceptance criterion?
 - Would the tests fail if the feature broke?
 - Are edge cases from the task's test cases covered?
+- **Assertion depth**: For mutation operations, do tests verify observable side effects — not just that the operation returned success? State changes should be asserted independently.
+- **Assertion precision**: When expected output is deterministic, do tests use exact comparison? Substring or partial matching masks formatting regressions and missing/extra content.
 - Flag both under-testing AND over-testing
 
 ### 4. Convention Adherence
@@ -61,6 +63,7 @@ Is this a sound design decision? Will it compose well with future tasks?
 - Are there coupling or abstraction concerns?
 - Will this cause problems for subsequent tasks in the phase?
 - Are there structural concerns that should be raised now rather than compounding?
+- Are concrete types used where data structures are known? Flag untyped escape hatches used where concrete types would be clearer and safer.
 
 ## Fix Recommendations (needs-changes only)
 

package/package.json

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

package/skills/technical-implementation/SKILL.md

@@ -49,7 +49,7 @@ Context refresh (compaction) summarizes the conversation, losing procedural deta
 
 1. **Re-read this skill file completely.** Do not rely on your summary of it. The full process, steps, and rules must be reloaded.
 2. **Check task progress in the plan** — use the plan adapter's instructions to read the plan's current state. Also read the implementation tracking file and any other working documents for additional context.
-3. **Check `task_gate_mode`, `fix_gate_mode`, `fix_attempts`, and `analysis_cycle`** in the tracking file — if gates are `auto`, the user previously opted out. If `fix_attempts` > 0, you're mid-fix-loop for the current task. If `analysis_cycle` > 0, you've completed analysis cycles — check for findings files on disk (`analysis-*.md` in `{topic}/`) to determine mid-analysis state.
+3. **Check `task_gate_mode`, `fix_gate_mode`, `fix_attempts`, and `analysis_cycle`** in the tracking file — if gates are `auto`, the user previously opted out. If `fix_attempts` > 0, you're mid-fix-loop for the current task. If `analysis_cycle` > 0, you've completed analysis cycles — check for findings files on disk (`analysis-*-c{cycle-number}.md` in `{topic}/`) to determine mid-analysis state.
 4. **Check git state.** Run `git status` and `git log --oneline -10` to see recent commits. Commit messages follow a conventional pattern that reveals what was completed.
 5. **Announce your position** to the user before continuing: what step you believe you're at, what's been completed, and what comes next. Wait for confirmation.
 

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

@@ -12,8 +12,11 @@ Apply standard quality principles. Defer to project-specific skills for framewor
 - Extract repeated logic after three instances (Rule of Three)
 - Avoid premature abstraction for code used once or twice
 
+### Compose, Don't Duplicate
+When new behavior is the logical inverse or subset of existing behavior, derive it from the existing abstraction rather than implementing independently. If you have a query for "ready items," the query for "blocked items" should be "open AND NOT ready" — not an independently authored query that could drift. Prefer mathematical relationships (derived = total - computed) over parallel computations that must be kept in sync.
+
 ### SOLID
-- **Single Responsibility**: Each class/function does one thing
+- **Single Responsibility**: Each class/function does one thing. Multi-step logic should decompose into named helper functions — each step a function, each name documents intent.
 - **Open/Closed**: Extend behavior without modifying existing code
 - **Liskov Substitution**: Subtypes must be substitutable for base types
 - **Interface Segregation**: Don't force classes to implement unused methods
@@ -25,6 +28,9 @@ Keep low. Fix with early returns and method extraction.
 ### YAGNI
 Only implement what's in the plan. Ask: "Is this in the plan?"
 
+### Concrete Over Abstract
+Prefer concrete types over language-level escape hatches that bypass the type system. Use specific types for data passing between layers, not untyped containers. If you need polymorphism, define a named interface/protocol with specific methods — don't pass untyped values. If you find yourself writing runtime type checks or casts inside a function, the signature is too abstract.
+
 ## Testability
 - Inject dependencies
 - Prefer pure functions
@@ -36,6 +42,8 @@ Only implement what's in the plan. Ask: "Is this in the plan?"
 - Deep nesting (3+)
 - Long parameter lists (4+)
 - Boolean parameters
+- Untyped parameters when concrete types are known at design time
+- Substring assertions in tests when exact output is deterministic
 
 ## Project Standards
 Check `.claude/skills/` for project-specific patterns.

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

@@ -79,6 +79,12 @@ Load **[invoke-analysis.md](invoke-analysis.md)** and follow its instructions.
 
 **STOP.** Do not proceed until all agents have returned.
 
+Commit the analysis findings:
+
+```
+impl({topic}): analysis cycle {N} — findings
+```
+
 → Proceed to **D. Dispatch Synthesis Agent**.
 
 ---
@@ -89,6 +95,12 @@ Load **[invoke-synthesizer.md](invoke-synthesizer.md)** and follow its instructi
 
 **STOP.** Do not proceed until the synthesizer has returned.
 
+Commit the synthesis output:
+
+```
+impl({topic}): analysis cycle {N} — synthesis
+```
+
 → If `STATUS: clean`, return to the skill for **Step 8**.
 
 → If `STATUS: tasks_proposed`, proceed to **E. Approval Gate**.
@@ -97,7 +109,7 @@ Load **[invoke-synthesizer.md](invoke-synthesizer.md)** and follow its instructi
 
 ## E. Approval Gate
 
-Read the staging file from `docs/workflow/implementation/{topic}/analysis-tasks.md`.
+Read the staging file from `docs/workflow/implementation/{topic}/analysis-tasks-c{cycle-number}.md`.
 
 Present an overview:
 
@@ -155,7 +167,15 @@ After all tasks processed:
 
 → If any tasks have `status: approved`, proceed to **F. Create Tasks in Plan**.
 
-→ If all tasks were skipped, return to the skill for **Step 8**.
+→ If all tasks were skipped:
+
+Commit the staging file updates:
+
+```
+impl({topic}): analysis cycle {N} — tasks skipped
+```
+
+Return to the skill for **Step 8**.
 
 ---
 
@@ -165,7 +185,7 @@ Load **[invoke-task-writer.md](invoke-task-writer.md)** and follow its instructi
 
 **STOP.** Do not proceed until the task writer has returned.
 
-Commit:
+Commit all analysis and plan changes (staging file, plan tasks, Plan Index File):
 
 ```
 impl({topic}): add analysis phase {N} ({K} tasks)

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

@@ -29,6 +29,7 @@ Dispatch **all three in parallel** via the Task tool. Each agent receives the sa
 3. **Project skill paths** — from `project_skills` in the implementation tracking file
 4. **code-quality.md path** — `../code-quality.md`
 5. **Topic name** — the implementation topic
+6. **Cycle number** — the current analysis cycle number (from `analysis_cycle` in the tracking file)
 
 Each agent knows its own output path convention and writes findings independently.
 

package/skills/technical-implementation/references/steps/invoke-task-writer.md

@@ -15,7 +15,7 @@ This step invokes the task writer agent to create plan tasks from approved analy
 Pass via the orchestrator's prompt:
 
 1. **Topic name** — the implementation topic
-2. **Staging file path** — `docs/workflow/implementation/{topic}/analysis-tasks.md`
+2. **Staging file path** — `docs/workflow/implementation/{topic}/analysis-tasks-c{cycle-number}.md`
 3. **Plan path** — the implementation plan path
 4. **Plan format reading adapter path** — `../../../technical-planning/references/output-formats/{format}/reading.md`
 5. **Plan format authoring adapter path** — `../../../technical-planning/references/output-formats/{format}/authoring.md`

package/skills/technical-implementation/references/tdd-workflow.md

@@ -42,7 +42,9 @@ But write **complete, functional implementations** - don't artificially minimize
 
 **Derive tests from plan**: Task's micro acceptance becomes your first test. Edge cases become additional tests.
 
-**Write test names first**: List all test names before writing bodies. Confirm coverage matches acceptance criteria.
+**Assert precisely**: For mutation operations (create, update, delete, state transitions), don't just assert the return value — verify observable side effects independently. A test that checks "operation succeeded" but ignores whether timestamps updated, related records changed, or output structure is correct will miss regressions that only affect side effects. Assert structured output by parsing and checking fields/values, not by string matching the serialized form.
+
+**Write test names first**: List all test names before writing bodies. Confirm coverage matches acceptance criteria. Then consider: invalid input types, boundary values, zero/nil/empty inputs, single vs multiple items, and success alongside failure paths — add tests for any that are relevant and non-trivial.
 
 **No implementation code exists yet.** If you're tempted to "just sketch out the class first" - don't. The test comes first. Always.