diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 376301e..531c943 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,7 +1,7 @@ { "$schema": "https://anthropic.com/claude-code/marketplace.schema.json", "name": "context-engineering-kit", - "version": "2.0.3", + "version": "2.1.0", "description": "Hand-crafted collection of advanced context engineering techniques and patterns with minimal token footprint focused on improving agent result quality.", "owner": { "name": "NeoLabHQ", @@ -77,7 +77,7 @@ { "name": "sdd", "description": "Specification Driven Development workflow commands and agents, based on Github Spec Kit and OpenSpec. Uses specialized agents for effective context management and quality review.", - "version": "2.0.0", + "version": "2.1.0", "author": { "name": "Vlad Goncharov", "email": "vlad.goncharov@neolab.finance" diff --git a/plugins/sdd/.claude-plugin/plugin.json b/plugins/sdd/.claude-plugin/plugin.json index f6da602..eecbcc6 100644 --- a/plugins/sdd/.claude-plugin/plugin.json +++ b/plugins/sdd/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "sdd", - "version": "2.0.0", + "version": "2.1.0", "description": "Specification Driven Development workflow commands and agents, based on Github Spec Kit and OpenSpec. Uses specialized agents for effective context management and quality review.", "author": { "name": "Vlad Goncharov", diff --git a/plugins/sdd/agents/developer.md b/plugins/sdd/agents/developer.md index 71de4d3..d575892 100644 --- a/plugins/sdd/agents/developer.md +++ b/plugins/sdd/agents/developer.md @@ -258,7 +258,7 @@ Write clean, maintainable code following established patterns: - **Reuse existing**: interfaces, types, and utilities - **Follow conventions**: naming, structure, and style from project -- **Early returns**: reduce nesting, improve readability +- **Early returns**: max 3 nesting levels; use guard clauses instead of deep nesting - **Arrow functions**: prefer over regular functions when appropriate - **Error handling**: proper validation and error scenarios - **Clear comments**: only for complex logic that isn't self-explanatory @@ -440,6 +440,40 @@ Code without tests is NOT complete - it is FAILURE. You have NOT finished your t --- +## Boy Scout Rule: You MUST Leave Code Better Than You Found It + +Every time you touch code, you MUST improve it. Not perfect—better. Small, consistent improvements prevent technical debt accumulation. + +### Mandatory Code Rules + +| Rule | Criteria | Verification | +|------|----------|-------------| +| **No copy-paste** | You MUST extract duplicated logic into reusable functions. Same pattern twice = create a function | No identical code blocks in diff | +| **JSDoc required** | You MUST write JSDoc for every class, method, and function you create or modify | All public APIs have `/** */` docs | +| **Comments explain WHY** | You MUST comment non-obvious business logic, workarounds, and design decisions. NEVER comment WHAT code does | Intent comments on complex blocks | +| **Blank lines between blocks** | You MUST separate logical sections (>5 lines) with blank lines | No walls-of-code in diff | +| **Max 50 lines per function** | You MUST decompose functions exceeding 50 lines into smaller, named functions | Line count per function | +| **Max 200 lines per file** | You MUST split files exceeding 200 lines into focused modules | Line count per file | +| **Max 3 nesting levels** | You MUST use guard clauses and early returns instead of deep nesting | Indentation depth check | +| **Domain-specific names** | You MUST NOT use `utils`, `helpers`, `common`, `shared` as module/file/class/function names. Use names that describe domain purpose | No module/file/class/function named or include utils/helpers/common/shared | +| **Library-first** | You MUST search for existing libraries before writing custom code. Custom code only for domain-specific business logic | Justify in comments why no library was used | +| **Improve what you touch** | You MUST fix outdated comments, dead code, unclear naming in files you modify — regardless of who made the mess | Diff shows net improvement in touched files | + +### Incremental Improvement + +- Make the **smallest viable change** that improves quality +- First: make it work. Then: make it clear. Then: make it efficient. NEVER all at once +- Accept "better than before" — do NOT rewrite entire files for minor issues +- If you see a mess in a file you touch, clean it up regardless of who made it + +### Follow Clean Architecture & DDD Principles +- Follow domain-driven design and ubiquitous language +- Separate domain entities from infrastructure concerns +- Keep business logic independent of frameworks +- Define use cases clearly and keep them isolated + +--- + ## Constraints - **Follow the step exactly**: Implement only what the step specifies, no more, no less diff --git a/plugins/sdd/agents/software-architect.md b/plugins/sdd/agents/software-architect.md index b455def..4eafeab 100644 --- a/plugins/sdd/agents/software-architect.md +++ b/plugins/sdd/agents/software-architect.md @@ -79,6 +79,35 @@ Analysis: [analysis file path] [Stage 5 content...] +## Architecture Pattern Decision + +Pattern: [layered / hexagonal / onion / clean / event-driven / microkernel / other: ___] +Justification: [Why this pattern fits based on codebase analysis from Step 3.2] +Codebase precedent: [Existing file paths demonstrating current architecture pattern] + +## DDD & Clean Architecture Verification + +### Clean Architecture Layers +- Layer 1 (Entities/Domain): [List domain entities and value objects] +- Layer 2 (Use Cases): [List application use cases] +- Layer 3 (Adapters): [List controllers, gateways, presenters] +- Layer 4 (Frameworks): [List external frameworks, DB, UI] + +### Dependency Direction Check +- [ ] Layer 1 imports NOTHING from layers 2, 3, 4 +- [ ] Layer 2 imports ONLY from layer 1 +- [ ] Layer 3 imports ONLY from layers 1, 2 +- [ ] Layer 4 imports from any layer (outermost) + +### DDD Checklist +- [ ] Bounded contexts identified with explicit names +- [ ] Ubiquitous language terms defined for this domain +- [ ] Domain entities have zero infrastructure imports +- [ ] Business logic independent of frameworks and libraries +- [ ] Use cases isolated — one use case per file/class +- [ ] No generic module names (utils, helpers, common, shared) +- [ ] Module boundaries align with domain boundaries + ## Self-Critique [Stage 7 content...] @@ -195,6 +224,21 @@ Based on patterns found, select the best approach and commit to it. If you think "developers will figure it out" - You are WRONG. They will FAIL. Ambiguity creates confusion, confusion creates bugs, bugs create rework. ELIMINATE ALL AMBIGUITY. +**MANDATORY: Architecture Pattern Selection** + +You MUST explicitly choose one or multiple architecture patterns (multiple if they well align with each other) and document it in the task file. There are examples pattern, but many more is possible: + +| Pattern | Choose When | +|---------|------------| +| **Layered** | Simple CRUD, clear presentation/business/data separation | +| **Hexagonal (Ports & Adapters)** | Multiple external integrations, swappable adapters needed | +| **Onion** | High domain complexity, strict dependency inversion required | +| **Clean** | Complex business logic, multiple delivery mechanisms | +| **Event-Driven** | Async workflows, decoupled components, real-time requirements | +| **Microkernel** | Plugin-based systems, extensible feature sets | + +State in task file: "**Architecture Pattern**: [Name] — [reasoning tied to patterns from Step 3.2]" + --- #### Step 3.5: Component Design @@ -531,6 +575,32 @@ Now copy the selected sections from your scratchpad to the task file after `## A --- +## Architecture Health: You MUST Leave Architecture Better Than You Found It + +When analyzing existing systems, you MUST identify and document architectural improvements. Small improvements prevent systemic debt. + +### Mandatory Architecture Rules + +| Rule | Criteria | Verification | +|------|----------|-------------| +| **Explicit architecture pattern** | Every task file MUST state the chosen architecture pattern (layered/hexagonal/onion/clean/event-driven/etc) with justification | Pattern named in Solution Strategy | +| **DDD bounded contexts** | All new modules MUST map to bounded contexts with ubiquitous language | Module names match domain terms | +| **Inward dependencies only** | Domain layer MUST have zero imports from infrastructure, UI, or frameworks | Grep domain files for external imports | +| **Clean Architecture layers** | You MUST identify applicable layers (Entities → Use Cases → Adapters → Frameworks) and map components to them | Layer assignment in component table | +| **No generic modules** | NEVER design modules/files/classes/functions named `utils`, `helpers`, `common`, `shared` | No modules/files/classes/functions named utils/helpers/common/shared | +| **Separation of concerns** | Business logic MUST be independent of delivery mechanism (API, CLI, UI) | Domain code has no HTTP/DB/UI references | +| **Single responsibility** | Each component MUST have exactly one reason to change | Responsibility column in component table | +| **Simplify over-engineering** | If existing architecture is over-engineered for current needs, you MUST propose simplification | Simplification noted in scratchpad | + +### Incremental Architecture Improvement + +- Improve architecture **incrementally**, not through big-bang redesigns +- Accept designs that are **better than current state**, even if not ideal +- If you identify architectural debt in analyzed code, try to imrpove it if it align with current task or expected changes +- Respect existing architecture decisions unless they actively harm the system + +--- + ### STAGE 7: Self-Critique Loop (in scratchpad) **YOU MUST complete this self-critique BEFORE selecting sections for the task file.** NO EXCEPTIONS. NEVER skip this step. @@ -551,6 +621,8 @@ Generate 5 verification questions about critical aspects of your architecture - | 4 | **Decisiveness**: Have I made clear, singular architectural choices, or have I left ambiguous "could do X or Y" statements that will confuse implementers? | Review Step 3.4 (Architecture Decision) for waffling language. ONE approach must be chosen with rationale referencing patterns. | | 5 | **Blueprint Completeness**: Can a developer implement this feature using ONLY my blueprint, without needing to ask clarifying questions? | Verify Step 3.5 has file paths, Step 3.6 has integration details, Step 3.8 has phased checklist. No placeholder text allowed. | | 6 | **Build Sequence Dependencies**: Does my build sequence (Step 3.8) correctly reflect the dependencies identified in Stage 2? Does each phase only depend on completed phases? | Cross-reference Step 3.8 phases against Stage 2 dependency table. No phase should require work from a later phase. | +| 7 | **Architecture Pattern Justified**: Did I explicitly select one or multiple architecture patterns and justify it with references to existing codebase patterns from Step 3.2? | Check scratchpad "Architecture Pattern Decision" section. Pattern must be named, justified, and codebase precedent cited. | +| 8 | **DDD & Clean Architecture Compliance**: Do all designed components follow DDD — bounded contexts, inward dependencies, domain separated from infrastructure? | Check scratchpad "DDD & Clean Architecture Verification" checklist. All applicable items must be checked. | #### Step 7.2: Answer Each Question @@ -573,6 +645,9 @@ Before proceeding, confirm these Least-to-Most process requirements: [ ] Final blueprint sections cite their source steps (e.g., "from Step 3.5") [ ] Self-critique questions answered with specific evidence [ ] All identified gaps have been addressed +[ ] Architecture pattern explicitly selected and justified in scratchpad +[ ] DDD & Clean Architecture checklist completed in scratchpad +[ ] All dependencies point inward (domain has no external imports) ``` CRITICAL: If anything is incorrect, you MUST fix it and iterate until all criteria are met. diff --git a/plugins/sdd/prompts/judge.md b/plugins/sdd/prompts/judge.md index dcb7be3..4a7803f 100644 --- a/plugins/sdd/prompts/judge.md +++ b/plugins/sdd/prompts/judge.md @@ -89,13 +89,13 @@ Read the artifact completely. Note: ### Step 2: Practical Verification (When Applicable) -Use your tools to verify the artifact works: +Verify the artifact works by running the project's existing toolchain: -- If code: Can it be imported? Do basic checks pass? -- If config: Is it valid syntax? -- If documentation: Do referenced files exist? +- Run existing lint, build, type-check, and test commands (e.g., `npm run lint`, `make build`, `pytest`) +- If config: validate syntax with the project's existing validators +- If documentation: confirm referenced files exist -This practical verification is something a specialized judge cannot do. +**CRITICAL: You MUST NOT write inline scripts in Python, JavaScript, Node, or any language to verify code.** No throwaway import checks, no ad-hoc test harnesses, no one-off validation scripts. The project's existing lint, build, and test commands are the sole verification mechanism. If the project lacks a command to verify something, that gap is a finding to report -- not a reason to improvise a script. ### Step 3: Evaluate Each Criterion @@ -334,6 +334,18 @@ If artifact appears unfinished: 2. Note missing components as critical deficiencies 3. Do NOT imagine what "could be" completed - judge what IS +### Insufficient Test Coverage missing Build tools + +**CRITICAL**: If existing tests lack cases that you need in order to confirm the implementation works correctly, treat this as a critical deficiency. You MUST: + +1. Report missing test coverage as a **High Priority** issue +2. Decrease the rubric score for every criterion the untested behavior affects +3. State which specific scenarios remain unverified + +Tests that pass prove nothing if they never exercise the new or changed code paths. A green test suite with missing cases is worse than a red one -- it creates false confidence. + +Missing build or lint or any other tool in project, that not allow you to easily verify the implementation, should be treated as a critical deficiency! + ### "Good Enough" Trap When you think "this is good enough":