Skip to content

Comments

Claude/analyze architectural issues #2

Open
cuioss-oliver wants to merge 829 commits intomainfrom
claude/analyze-architectural-issues-011CUrJMLhbdWLWTrSrveYMs
Open

Claude/analyze architectural issues #2
cuioss-oliver wants to merge 829 commits intomainfrom
claude/analyze-architectural-issues-011CUrJMLhbdWLWTrSrveYMs

Conversation

@cuioss-oliver
Copy link
Collaborator

@cuioss-oliver cuioss-oliver commented Nov 7, 2025

No description provided.

@gemini-code-assist
Copy link

gemini-code-assist bot commented Nov 7, 2025

Summary of Changes

Hello @cuioss, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request marks the completion of a significant architectural migration within the CUI LLM rules system. The primary goal was to resolve a platform constraint that prevented sub-agents from using the Task tool, which could lead to infinite nesting. The solution introduces a clear separation of concerns by defining new architectural patterns and enforcing strict rules. Agents are now designed as focused executors, while commands are responsible for orchestrating workflows, delegating tasks, and handling verification. This refactoring enhances the system's robustness, reusability, and maintainability, ensuring a more stable and scalable foundation for future development without impacting existing user-facing functionality.

Highlights

  • Agent Nesting Migration Complete: The pull request successfully completes a comprehensive architectural migration to address agent nesting limitations within the CUI LLM rules system, achieving 100% compliance with new architectural rules.
  • New Architectural Patterns: Three core architectural patterns have been established and implemented: 'Self-Contained Command' for single operations, 'Three-Layer Design' for batch operations, and 'Fetch + Triage + Delegate' for smart orchestration.
  • Critical Rules Enforced: New critical rules are now enforced: Rule 6 (Agent Delegation Constraints), Rule 7 (Maven Execution Principle), and Rule 8 (Three-Layer Command Pattern), ensuring agents are focused executors and commands handle orchestration.
  • Enhanced Diagnostic Tools: Diagnostic tools have been updated with new checks (Check 6 for Task Tool Misuse and Check 7 for Maven Anti-Pattern) to proactively prevent and reactively detect architectural violations during agent creation and analysis.
  • Extensive Bundle Refactoring: All affected bundles, including cui-documentation-standards, cui-maven, cui-java-expert, cui-workflow, and cui-plugin-development-tools, have undergone significant refactoring, involving the deletion of 5 agents, creation of 6 new agents, modification of 7 agents, creation of 7 new commands, and updating of 6 commands.
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist[bot]
gemini-code-assist bot reviewed Nov 7, 2025
View reviewed changes
Copy link

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This is a significant and well-executed architectural refactoring to align with platform constraints on agent delegation. The changes are extensive, correctly refactoring agents into focused executors and moving orchestration logic into commands that follow the new, clearly defined architectural patterns. The addition of diagnostic tools to enforce these new rules is a great touch. My review identifies a few inconsistencies in the supporting documentation (migration summary, plan, and test results) that should be updated to accurately reflect the final, completed state of this large-scale effort.

claude/architectural-issues/MIGRATION-SUMMARY.md Outdated
Comment on lines 16 to 26
**cui-java-expert (100% Complete - 3 implementation tasks)**:
- Commit e39daa6: Updated cui-java-task-manager to use self-contained commands
- Commit e39daa6: Updated cui-log-record-enforcer to use logging-violation-analyzer
- Commit e39daa6: Updated README.md with new architecture (5 agents, 5 commands)

**cui-workflow (52% → 100% Complete - 5 implementation tasks)**:
- Commit 81ca930: Deleted pr-review-responder agent
- Commit 81ca930: Created /execute-task command (Pattern 1)
- Commit 81ca930: Updated /cui-handle-pull-request to use Pattern 3 commands
- Commit 81ca930: Updated /cui-implement-task for atomic vs batch pattern
- Commit 81ca930: Updated task-reviewer agent (removed Task/SlashCommand, added delegation info)
Copy link

@gemini-code-assist gemini-code-assist bot Nov 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

This summary report contains several inconsistencies that make it difficult to understand the final state of the migration. For example:

  • The cui-java-expert and cui-workflow sections in the "Session Summary" show different completion numbers and tasks compared to their detailed sections later in the document (e.g., lines 124 and 166).
  • Several sections like cui-java-expert (line 124), cui-workflow (line 182), and "Next Steps" (line 332) list "Remaining" tasks, which contradicts the overall 100% completion status.

Please update the document to be internally consistent and accurately reflect the final, completed state of the migration.

cuioss-oliver pushed a commit that referenced this pull request Nov 7, 2025
@claude
docs(migration): fix documentation inconsistencies per Gemini review
f961f98 
Address Gemini code review feedback on PR #2:

1. MIGRATION-SUMMARY.md:
   - Update cui-java-expert section from 73% to 100% complete
   - Update cui-workflow section to show all 23 tasks complete
   - Remove "Remaining" tasks sections (all complete)
   - Update Next Steps to reflect 100% completion

2. migration-plan.md:
   - Fix contradictory task status markers
   - Replace "COMPLETED: In progress (next commit)" with actual commit hashes
   - Updated 5 tasks with proper commit references (a2fd0fe, 23deb2d)

3. test-results.md:
   - Update all agent test statuses from "NOT YET TESTED" to "CONFIRMED"
   - Add commit references for each fixed violation
   - Update Test Summary table with all 8 agents showing fixes
   - Change status from "DETECTION PATTERNS VALIDATED" to "ALL VIOLATIONS RESOLVED"

All documentation now consistently reflects 100% migration completion (51/51 tasks).
@cuioss-oliver cuioss-oliver changed the title Claude/analyze architectural issues 011 c ur jm lhbd wlw tr srve y ms Claude/analyze architectural issues Nov 7, 2025
cuioss-oliver and others added 26 commits December 12, 2025 23:24
@cuioss-oliver @claude
fix(plugin-task-plan-agent): use correct manage-log script call pattern
ac928d7 
Replace skill invocation syntax with direct script execution. The agent
was passing two arguments (message + detail) but manage-log only accepts
a single message argument.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
refactor(plugin-solution-outline): extract modular standards documents
3129f63 
- Extract path-single-workflow.md for isolated component changes
- Extract path-multi-workflow.md for cross-cutting changes
- Extract reference-tables.md for inventory, mapping, and error handling
- Extract script-verification.md for conditional test requirements
- Add required skills loading (plugin-architecture, plugin-script-architecture)
- Add verification requirements with /plugin-doctor command
- Reduce main SKILL.md from 512 to 252 lines (~50% reduction)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
fix(plan-init): add delete-plan command and fix shell expansion permi…
bccada0 
…ssion issue

- Add delete-plan command to manage-files script for deleting entire plan directories
- Fix permission prompt issue by removing $(git branch --show-current) shell expansion from plan-init skill documentation
- Create plan-overwrite.md standard documenting the Replace flow for existing plans
- Add 3 tests for delete-plan command (success, not found, invalid id)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
refactor(manage-task): migrate add command from CLI params to stdin-b…
d512d11 
…ased API

Breaking change: The `add` command now reads task definition from stdin
instead of CLI parameters. This avoids shell metacharacter permission
issues when verification commands contain pipes, wildcards, or quotes.

Old API (removed):
  manage-task add --plan-id X --title "Y" --deliverables 1 2 \
    --verification-commands "grep | wc -l"

New API (stdin with heredoc):
  manage-task add --plan-id X <<'EOF'
  title: Y
  deliverables: [1, 2]
  domain: java
  verification:
    commands:
      - grep | wc -l
  EOF

Changes:
- Add parse_stdin_task() function for TOON format parsing
- Simplify argparse for add command to only --plan-id
- Add 'generic' to VALID_DOMAINS for generic plan support
- Update all 54 tests to use new stdin-based API
- Update documentation in SKILL.md files across bundles
- Update task-plan skills (java, js, plugin) with heredoc examples
- Update agent documentation and compliance standards

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
feat(plan-marshall): add tools-analyze-user-prompted command
d1752cf 
New command to diagnose permission prompts by analyzing screenshots,
descriptions, and chat history to identify source components and
provide actionable solutions.

Includes sample section documenting the shell metacharacter issue
that was solved by the stdin-based manage-task API refactoring.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
fix(pm-workflow): align script names with skill names for consistency
5249b1d 
Rename scripts to match their parent skill names:
- manage-plan-document.py → manage-plan-documents.py
- manage-task.py → manage-tasks.py

This resolves naming inconsistencies where skill names were plural
but script names were singular, causing confusion in notation patterns.

Additional fixes:
- Implement manage-log read subcommand for work log access
- Fix planning-compliance.md to document correct APIs
- Update all 35+ files with corrected script notations
- Add comprehensive tests for manage-log read functionality

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
refactor(plugin-development): move tools-analyze-user-prompted to pm-…
ff48a48 
…plugin-development

Move permission prompt analysis command from plan-marshall to
pm-plugin-development bundle where it better fits with plugin
architecture and component development tooling.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
feat(pm-plugin-development): add tools-analyze-script-failures comman…
d51553e 
…d and skill

Add diagnostic tooling for analyzing script failures from conversation history:
- New skill: analyze-script-failures with origin tracing and fix proposals
- New command: tools-analyze-script-failures as thin wrapper
- Integration with verification skill for deep analysis follow-up

The command analyzes script failures (non-zero exits) to identify:
- Source component (command/agent/skill) that triggered the failure
- How LLM interpreted instructions to produce the failed call
- Root cause categorization with specific fix proposals
- Lessons learned integration for future reference

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
feat(pm-workflow): enforce contract compliance with automatic validation
7c6c0b7 
- Add automatic deliverable contract validation on solution outline write
- Add file path validation for task steps (rejects descriptive text)
- Add Contract Compliance sections to all domain skills (java, frontend, plugin)
- Add Invalid Examples (anti-patterns) to deliverable and task contracts
- Update tests to use file paths instead of descriptive steps

The validation is now mandatory (no --strict flag) - non-compliant content
is rejected before file creation. This ensures all deliverables have proper
Metadata blocks and all tasks use file paths from Affected files sections.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
fix(pm-plugin-development): correct script API references preventing …
c6e8c17 
…agent failures

- Fix plugin-solution-outline-agent logging instructions to use correct
  manage-log CLI format instead of invalid skill YAML format
- Add python3 execute-script.py prefix to script notation reference
- Update pattern-usage-examples.md to use actual marketplace-inventory API
- Add clarifying comments to conceptual examples in reference docs
  distinguishing fictional scan-inventory.sh from actual API

These fixes prevent agents from inventing invalid script parameters
like --format json that cause runtime failures.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
docs(plan-type-api): enhance contract compliance documentation
2c437e1 
- deliverable-contract.md: Allow depends field to use "N. Title" format
  for improved readability while maintaining number-based parsing
- task-contract.md: Clarify input vs stored formats for steps field,
  distinguishing YAML input from TOON tabular storage format
- planning-compliance.md: Add Plan-Type-API Contract Verification section
  with phase-by-phase verification requirements and common violations

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
feat(verification): add post-phase verification protocol and process-…
cd98e27 
…first principle

Enhance verification skill with mandatory post-phase verification protocol
that must be executed after every phase transition (init→refine→execute→finalize).

Changes:
- Add MANDATORY Post-Phase Verification Protocol to planning-compliance.md
  - Step 1: Chat history error check
  - Step 2: Script execution log check (detect retry patterns)
  - Step 3: Plan-type-API contract verification
  - Step 4: Status consistency check
- Add "Process vs Data Priority" section to verification SKILL.md
  - Clarifies verification mode focuses on fixing COMPONENTS, not data
  - Wrong: "retry succeeded, continuing"
  - Right: "STOP, fix the agent that failed"
- Add proactive constraints to plugin-solution-outline-agent
  - MUST NOT use wildcards in affected files
  - MUST enumerate every file explicitly
- Fix manage-log.py to output raw_content for script execution logs

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
fix(script-executor): skip logging for successful manage-log calls
400da11 
Logging scripts (manage-log work/script) were creating meta-logging noise
by logging their own successful executions. Now SUCCESS entries for
plan-marshall:logging:manage-log are skipped, while errors are still logged.

- Add should_skip_logging() function to filter meta-logging
- Add SILENT_ON_SUCCESS constant for extensibility
- Add TDD tests for skip logging behavior

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver
feat(plan-config): update compatibility setting to 'breaking' and enh…
a898b69 
…ance delete operations documentation
@cuioss-oliver @claude
fix(verification): enforce contract compliance and manage-log API usage
900a433 
- plugin-task-plan: Mark context_skills as MANDATORY even when empty
- verification SKILL.md: Add explicit 4-step Post-Phase Verification Protocol
- planning-compliance.md: Replace direct tail/cat with manage-log API (limit=20)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
refactor(logging): unify log levels by removing SUCCESS in favor of INFO
5ffea29 
Remove SUCCESS as a valid log level and use INFO for all successful
operations. This simplifies the logging API to three levels: INFO,
WARN, ERROR.

Changes:
- Update VALID_LEVELS in plan_logging.py and manage-log.py
- Change log_script_execution to use INFO for exit_code=0
- Update documentation in logging SKILL.md, log-format.md
- Update workflow documentation using work log commands
- Update tests to expect INFO instead of SUCCESS

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
feat(plan-type-api): add execute phase contracts and plugin-plan-exec…
d474915 
…ute skill

Add implementation delegation and implement agent contracts to plan-type-api:
- implementation-delegation-contract.md: How tasks specify execution delegation
- implement-agent-contract.md: Agent input/output interface

Add plugin-plan-execute skill for plugin domain execution:
- SKILL.md: Execution workflow with step iteration
- standards/step-execution.md: Step execution patterns

Update domain frontmatter contract to include implement_agent field.
Refactor plugin-implement-agent to minimal wrapper pattern.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
refactor(naming): rename plugin-plan-execute to plugin-plan-implement…
7c8766a 
… (Option B)

Unify naming convention: domain-level skills use "implement" to distinguish
from orchestration-level "execute" (plan-execute skill/command).

Changes:
- Rename skill: plugin-plan-execute → plugin-plan-implement
- Update plugin.json skill reference
- Update plugin-implement-agent to load plugin-plan-implement
- Update plan-type-plugin documentation
- Update implement-agent-contract domain skill column
- Update planning-inventory patterns and derived components table

Architecture:
- execute = orchestration level (plan-execute skill/command)
- implement = domain level (plugin-plan-implement, java-plan-implement, etc.)

All 49 tests pass.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
refactor(plan-type-api): implement unified '-plan-' infix naming (Opt…
573c9ea 
…ion B)

- Rename solution outline agents to include '-plan-' infix:
  - java-solution-outline-agent → java-plan-solution-outline-agent
  - js-solution-outline-agent → js-plan-solution-outline-agent
  - plugin-solution-outline-agent → plugin-plan-solution-outline-agent
  - plugin-implement-agent → plugin-plan-implement-agent

- Create new implement agents and skills for Java and JavaScript:
  - java-plan-implement-agent with java-plan-implement skill
  - js-plan-implement-agent with js-plan-implement skill

- Update plan-type skills with implement_agent field:
  - plan-type-java, plan-type-javascript, plan-type-plugin
  - plan-type-generic with null values for consistency

- Update plan-type-api contracts and documentation:
  - domain-frontmatter-contract.md
  - implement-agent-contract.md
  - SKILL.md

- Update planning-inventory patterns to detect '*-plan-*' components

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
refactor(pm-dev-java): separate CUI-specific standards into pm-dev-ja…
6ee3cdd 
…va-cui bundle

Major refactoring to separate general Java development standards from CUI library-specific patterns:

**New bundle: pm-dev-java-cui** (4 skills)
- cui-logging: CuiLogger, LogRecord, DSL patterns
- cui-testing: Test generators, value object contracts, JUL testing
- cui-http: CUI HTTP client patterns
- cui-testing-http: MockWebServer patterns

**Renamed skills in pm-dev-java** (9 → 12 skills)
- cui-java-core → java-core, java-null-safety, java-lombok
- cui-java-unit-testing → junit-core, junit-integration
- cui-java-cdi → java-cdi, java-cdi-quarkus
- cui-javadoc → javadoc
- cui-java-maintenance → java-maintenance

**Updated references** (59+ files)
- All agents, commands, and cross-bundle skill references updated
- Test files and project configuration updated
- No broken references remain (verified via grep)

This separation enables:
- Generic Java projects to use only pm-dev-java skills
- CUI projects to additionally load pm-dev-java-cui skills
- Cleaner skill composition without forced CUI dependencies

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
fix(refs): update cross-skill references after cui-* skill renaming
04f1963 
Updates all references in standards, commands, and skills to use new
skill names after the pm-dev-java refactoring:

- cui-java-core → pm-dev-java:java-core
- cui-java-unit-testing → pm-dev-java:junit-core
- cui-javadoc → pm-dev-java:javadoc
- cui-java-cdi → pm-dev-java:java-cdi
- cui-java-maintenance → pm-dev-java:java-maintenance
- Logging standards → pm-dev-java-cui:cui-logging
- Test generators → pm-dev-java-cui:cui-testing

Fixes broken cross-skill references in:
- junit-core, java-core, java-cdi, java-cdi-quarkus skills
- java-maintenance standards (compliance-checklist, refactoring-triggers)
- java-enforce-logrecords, java-maintain-logger commands
- pm-dev-builder, pm-documents cross-bundle references

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
refactor(skills): consolidate standards and reduce duplication
356de73 
- java-null-safety: integrate standards into SKILL.md (380 lines)
- junit-integration: integrate standards into SKILL.md (247 lines)
- java-plan-implement: integrate standards into SKILL.md (309 lines)
- cui-logging: merge logging-enforcement-patterns into logging-standards
- java-cdi-quarkus: reference junit-integration instead of duplicating
- coverage-analysis-pattern: condense from 724 to 289 lines (~60% reduction)

Net reduction: ~1400 lines across 12 files

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
refactor(java-cdi): move cdi-container.md to java-cdi-quarkus/contain…
c99e88a 
…er.md

Container/Docker standards are Quarkus-specific, not generic CDI.

Changes:
- Move java-cdi/standards/cdi-container.md → java-cdi-quarkus/standards/container.md
- Update java-cdi/SKILL.md: remove container reference, add cross-reference note
- Update java-cdi-quarkus/SKILL.md: add container.md to workflow and table
- Update integration-testing.md: fix references to use local container.md

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
refactor(java-cdi): move security.md to quarkus, collapse to single S…
1331631 
…KILL.md

Security standards are Quarkus-specific (OWASP Docker, container security).
CDI aspects integrated directly into SKILL.md (252 lines, condensed from 490).

Changes:
- Move java-cdi/standards/cdi-security.md → java-cdi-quarkus/standards/security.md
- Integrate cdi-aspects.md content into java-cdi/SKILL.md
- Delete java-cdi/standards/ folder entirely
- Update java-cdi-quarkus/SKILL.md with security.md reference
- Update container.md and integration-testing.md references

Net reduction: ~847 lines

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
refactor(java-lombok): collapse to single SKILL.md (265 lines)
1e431d7 
Integrate java-lombok-patterns.md into SKILL.md with condensed content:
- Reduced from ~562 combined lines to 265 lines (~53% reduction)
- Consolidated all Lombok annotation documentation
- Preserved core patterns: @DeleGate, @builder, @value, @UtilityClass
- Added comparison table for Records vs @value
- Condensed pitfalls into table format

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
refactor(skill_domains): restructure to system + technical domain pat…
68cc15a 
…tern

- Add system domains: `system`, `plugin-development`
- Restructure technical domains to core/implementation/testing pattern:
  - java-core, java-implementation, java-testing
  - javascript-core, javascript-implementation, javascript-testing
- Update all documentation with new domain structure
- Update marshal-defaults.json template and local config
- Add tests for plugin-development domain operations

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
cuioss-oliver and others added 30 commits January 10, 2026 22:32
@cuioss-oliver @claude
feat(scripts): enable cross-skill imports via direct Python imports
b5f90c3 
- Update _maven_cmd_discover.py to use direct imports instead of subprocess CLI calls
- Add PYTHONPATH setup to test/conftest.py and test/run-tests.py mirroring executor behavior
- Update logging SKILL.md to document direct import pattern
- Remove unnecessary _log wrapper, use log_entry directly

Scripts run via executor can now import from any skill without sys.path manipulation.
Tests mirror this by setting up PYTHONPATH automatically.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
docs(testing): document cross-skill imports in test infrastructure
c6a5ed5 
- Add "Cross-Skill Imports in Tests" section to testing-standards.md
- Remove _get_ext_default wrapper, use ext_defaults_get directly
- Explain how test runner and conftest set up PYTHONPATH

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
refactor(scripts): apply direct import patterns and add logging
3e5b76e 
- Remove sys.path manipulation from all pm-dev-java scripts
- Use direct imports (PYTHONPATH set by executor)
- Add logging at decision points (parse results, errors, timeouts)
- Scripts modified: _maven_cmd_parse, _gradle_cmd_parse,
  _maven_execute, _gradle_execute, _gradle_cmd_discover

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
refactor(tests): remove sys.path manipulation, use conftest PYTHONPATH
14bf500 
- test_maven_cmd_parse.py: Use conftest pattern for cross-skill imports
- test_gradle_cmd_parse.py: Use conftest pattern for cross-skill imports
- test_discover_modules.py: Use conftest pattern for cross-skill imports
- test_gradle_discover_modules.py: Use conftest pattern for cross-skill imports
- test_profiles.py: Add conftest import for PYTHONPATH setup
- test_maven_discover_modules.py (integration): Simplify sys.path setup
- test_gradle_discover_modules.py (integration): Simplify sys.path setup

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
refactor(architecture): replace proposed_skill_domains with skills_by…
6db29cf 
…_profile

- Remove legacy flat list field in favor of profile-keyed structure
- Add Step 6d-2 for key dependencies enrichment in workflow
- Add reasoning requirements for all enrichment steps
- Update all consumers (manage-solution-outline) to read new field
- Remove enrich_skills command (superseded by enrich skills-by-profile)
- Update documentation across analyze-project-architecture and pm-workflow

BREAKING: proposed_skill_domains field no longer exists in llm-enriched.json

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
refactor(extension-api): apply direct import patterns and add logging
ab47302 
Scripts:
- extension.py: Remove _ensure_extension_api_importable(), add log_entry
- _module_aggregation.py: Replace stderr print with log_entry

Tests:
- Replace sys.path manipulation with conftest PYTHONPATH pattern
- All 6 test files updated: test_build_{format,discover,parse,result}.py,
  test_extension.py, test_extension_base.py

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
docs(architecture): simplify module-graph-format to tree output
8cf6d4b 
Update documentation to reflect the simplified dependency tree output:
- Replace complex TOON format with simple indented tree
- Single module: just "module: name"
- Multi-module: dependency tree with "  - " indentation
- Remove nodes/edges/layers tables (no longer in output)
- Update examples to match actual output

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
refactor(scripts): remove sys.path manipulation, use PYTHONPATH
196f40e 
- Remove sys.path.insert from 11 production scripts in plan-marshall
- Remove sys.path.insert from 46 test files in test/plan-marshall
- Replace subprocess CLI call with direct import in ci_health.py
- Update test runner to include test/ in PYTHONPATH for conftest access
- All tests passing (46/46)

Scripts now rely on executor-provided PYTHONPATH for cross-skill imports.
Tests use conftest.py PYTHONPATH setup instead of manual sys.path.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
refactor(scripts): apply direct import patterns to pm-dev-frontend
f58dc42 
- Remove sys.path manipulation from 7 production scripts
- Remove sys.path manipulation from 7 test files
- Add structured logging to npm.py entry point
- Use importlib for Extension import to avoid naming conflicts

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
refactor(pm-dev-java): apply direct import patterns to profiles.py
b26918f 
- Remove sys.path manipulation from profiles.py (use PYTHONPATH)
- Update test_profiles.py to use TestRunner from conftest
- Add type ignore comments for IDE compatibility

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
refactor(pm-dev-java-cui): apply script rules to extension.py
3334b16 
Apply learnings from script-rules.md:
- Remove sys.path manipulation for cross-skill imports
- Add type: ignore comments for IDE compatibility
- Add sensible logging for config_defaults

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
refactor(pm-documents): apply script rules to all scripts
65653ca 
Add plan_logging imports and log_entry calls following script-rules.md:
- manage-adr.py: log create, update, delete operations with ADR prefix
- manage-interface.py: log create, update, delete operations with IFACE prefix
- _cmd_format.py: log files modified count with DOCS-FORMAT prefix
- _cmd_validate.py: log non-compliant files with DOCS-VALIDATE prefix
- _cmd_verify_links.py: log broken links with DOCS-LINKS prefix
- _cmd_review.py: log issues found with DOCS-REVIEW prefix
- _cmd_analyze_tone.py: log promotional language with DOCS-TONE prefix

All logging uses sensible INFO level for successful operations and
ERROR level for failures. Verified with all pm-documents tests passing.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
refactor(pm-plugin-development): apply script rules to all scripts
efb53f5 
Apply learnings from script-rules.md to all scripts and tests:

Production scripts:
- cmd_validate.py: Narrow Exception to (ValueError, IndexError)
- doctor-marketplace.py: Remove sys.path manipulation
- _analyze.py: Remove sys.path manipulation
- _cmd_extension.py: Remove _ensure_extension_base_importable function
- _analyze_crossfile.py: Narrow Exception to (OSError, IOError)

Test files (7):
- Remove redundant sys.path.insert lines (conftest handles PYTHONPATH)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
refactor(pm-requirements): apply script rules to extension.py
1839bc0 
Add type: ignore[import-not-found] comment for IDE compatibility.
No logging added - extension only returns static metadata.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
refactor(pm-workflow): apply script rules to all scripts
e4dc967 
- Remove sys.path manipulation, use direct imports
- Add sensible logging with plan_logging.log_entry()
- Fix silent error handling (catch specific exceptions)
- Add type: ignore comments for IDE warnings
- Update tests to use conftest PYTHONPATH setup

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
docs(plugin-script-architecture): add cross-skill integration standards
c0eaad6 
Add new standards/cross-skill-integration.md covering:
- PYTHONPATH setup by executor
- No sys.path manipulation rule
- Type ignore comment conventions
- Standard cross-skill APIs (plan_logging, run_config, file_ops, toon_parser)
- Direct imports vs subprocess guidelines
- No silent error handling prohibition
- Subprocess parameter guidelines
- Internal module naming conventions (_script.py)
- Test infrastructure integration

Update SKILL.md and add cross-references to python-implementation.md
and testing-standards.md.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
fix(analyze-project-architecture): fix argparse naming collision in m…
f593f93 
…odules command

Fix two bugs in architecture CLI:

1. Naming collision: The --command argument for 'modules' subparser used
   the same attribute name as the subparser dest (args.command). When running
   'architecture modules', argparse sets args.command='modules', causing
   cmd_modules to incorrectly filter by command='modules' instead of listing
   all modules. Fixed by using dest='filter_command'.

2. Missing returns: DataNotFoundError handlers called error_data_not_found()
   but didn't return its exit code, causing functions to return None instead
   of 1 on error.

Added 4 regression tests using TDD approach to prevent future regressions.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
fix(marshall-steward): reorder wizard to apply extension defaults bef…
2b4a86c 
…ore discovery

Move "Apply Extension Defaults" (Step 4b) before "Discover Project
Architecture" (Step 3) so profile filtering happens at discovery time.

Changes:
- Step 3: Apply Extension Defaults (sets skip list and mappings)
- Step 4: Discover Project Architecture (uses filtered profiles)
- Step 5-12: Renumbered subsequent steps

Also renamed "Detected domains (auto-configured)" to "Available Plugins
(installed)" for clarity.

This ensures derived-data.json contains only filtered profiles from the
first discovery pass, eliminating the need for a second discovery.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
fix(architecture): improve module discovery and profile mapping
b476eb3 
Three fixes based on OAuth-Sheriff project analysis:

1. Rename canonical command 'performance' to 'benchmark'
   - SKILL.md: Update AskUserQuestion options and canonical table
   - profiles.py: Update PROFILE_PATTERNS key
   - wizard-flow.md, menu-configuration.md: Update AskUserQuestion labels
   - run_config.py: Update VALID_PROFILE_CANONICALS
   - run-config-format.md, profile-mapping.md: Update documentation

2. Add verify/install commands for pom-only modules
   - POM modules now get verify and install commands for aggregation
   - clean-install and package remain jar/war only

3. Fix module ordering - root module first
   - Add sort key to ensure module with path "." is always first
   - Alphabetical ordering for remaining modules

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
feat(architecture): add test resources and fix graph documentation
905af5d 
- Add real marshal-steward architecture data as test resources
- Fix module filtering to check purpose field for leaf modules
- Update graph documentation to match actual tree output format
- Remove duplicated format spec from SKILL.md (reference only)
- Add parallel execution note to ordering guidance

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
fix(tests): update test expectations to match current code behavior
6ea45a9 
- Replace 'performance' canonical with 'benchmark' in profile mapping tests
- Update classify_profile tests to expect 'benchmark' instead of 'performance'
- Update pom aggregator test to expect verify command (code now provides it)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
feat(script-executor): add PLAN_DIR_NAME configuration for path isola…
3532e4a 
…tion

- Add PLAN_DIR_NAME env var support in generate-executor.py
- Inject PLAN_DIR_NAME constant into generated executor template
- Update _build_parse.py to use configurable plan directory name
- Update _build_result.py LOG_BASE_DIR to use PLAN_DIR_NAME
- Update _doctor_shared.py TEMP_DIR to use PLAN_DIR_NAME
- Clarify comment in _architecture_core.py (uses relative paths)

Enables configuration of plan directory name for testing and
alternative deployments via PLAN_DIR_NAME environment variable.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
feat(script-executor): export PLAN_DIR_NAME to child scripts
2841e80 
- Add env.setdefault('PLAN_DIR_NAME', PLAN_DIR_NAME) in executor
- Respects existing values (e.g., set by test infrastructure)
- Update _architecture_core.py to use PLAN_DIR_NAME from env
- Completes centralized path configuration architecture

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
docs: document PLAN_DIR_NAME environment variable configuration
bde9c10 
- Add Environment Variables section to script-executor SKILL.md
- Add path configuration patterns to python-implementation.md
- Update test infrastructure (conftest.py, run-tests.py) with PLAN_DIR_NAME
- Add checklist item for env var usage in script quality checklist

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
refactor(test): unify test infrastructure to use PLAN_BASE_DIR env var
d95176c 
- Remove --project-dir CLI argument from run_config.py (test workaround)
- Script now reads PLAN_BASE_DIR env var with fallback to current directory
- Update test_run_config.py to use PlanTestContext instead of TempDirContext
- Update test_warning_api.py to use PlanTestContext
- Update conftest.py PlanTestContext to clean up .plan directory on exit
- Fix test_await_until.py to explicitly set PLAN_BASE_DIR

This removes ~180 lines of duplicated test infrastructure code and
ensures all tests use the centralized PLAN_BASE_DIR/PLAN_DIR_NAME
environment variable approach.

All 90 tests pass.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
refactor(test): remove legacy test_init_default_project_dir test
71e9dea 
This test was using os.chdir() and direct subprocess.run() instead of
the unified run_script() helper. It tested legacy cwd-based behavior
that no longer applies now that scripts use PLAN_BASE_DIR env var.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
refactor(test): remove custom TempDirContext classes from test files
342330a 
Replace custom TempDirContext classes with standard tempfile.TemporaryDirectory
or named contextmanager functions. This eliminates duplicate context manager
implementations across test files.

Changes:
- test_manage_json_file.py: Use tempfile.TemporaryDirectory directly
- test_manage_memory.py: Replace with memory_test_context() that sets PLAN_BASE_DIR
- test_extension.py: Use tempfile.TemporaryDirectory directly
- test_maven.py: Remove TempDirContext, use tempfile.TemporaryDirectory
- test_maven_run.py: Replace with mock_maven_project() contextmanager + cwd param
- test_gradle.py: Remove TempDirContext, use tempfile.TemporaryDirectory
- test_gradle_run.py: Replace with mock_gradle_project() contextmanager + cwd param

All tests remove unnecessary os.chdir() calls, using explicit cwd parameter to
run_script() where directory context is needed.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
fix(architecture): remove non-portable root path from derived-data.json
6dc8681 
The "root" field in derived-data.json contained an absolute path
(e.g., /Users/oliver/git/project) which made the file non-portable
across machines. Removed this field since:
- Project name already identifies the project
- The project_dir argument is passed where needed
- Absolute paths break when files are shared or moved

Changes:
- Remove root field generation in api_discover()
- Remove root field output in cmd_derived() and cmd_info()
- Update tests to not include root field in test data
- Update architecture-persistence.md documentation

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
chore: update all plugin versions to 0.1-BETA
5886670 
Standardizes version across all bundles and marketplace configuration
to reflect beta status of the plugin system.

Updated files:
- 8 production bundle plugin.json files
- marketplace.json metadata
- 4 SKILL.md frontmatter versions in pm-requirements
- 3 test fixture plugin.json files

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@cuioss-oliver @claude
refactor(test): remove non-portable root path from test files
a0dc77d 
Continue cleanup of the non-portable "root" field from test data
and JSON resource files. All test fixtures now use only the portable
"name" field for project identification.

Updated files:
- test/conftest.py: create_raw_project_data helper
- test/plan-marshall/analyze-project-architecture/test_cmd_enrich.py
- test/plan-marshall/plan-marshall-config/test_helpers.py
- test/plan-marshall/plan-marshall-config/test_cmd_modules.py (3 occurrences)
- test/plan-marshall/plan-marshall-config/test_detection.py (3 occurrences)
- test/plan-marshall/plan-marshall-config/test_command_resolution.py
- test/pm-dev-java/integration/discover_modules/test_maven_discover_modules.py
- test/pm-dev-java/maven-profile-management/test_profiles.py
- test/pm-dev-java/integration/discover_modules/resources/*/derived-data.json (3 files)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

1 more reviewer

@gemini-code-assist gemini-code-assist[bot] gemini-code-assist[bot] left review comments

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@cuioss-oliver